/webhooks

POST/v1/agent/webhooks

Create a webhook endpoint

Requires API-key authentication (agentAuth, agentId).

Purpose: create an outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:webhooks:manage.

Idempotency: required.

Request:

json

example

{
  "url": "https://example.com/hightop/webhook",
  "description": "Production webhook",
  "event_types": ["payment.executed", "conversion.executed"]
}

event_types accepts only currently subscribable event types, not every reserved event in the full vocabulary.

Response:

json

example

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "url": "https://example.com/hightop/webhook",
    "description": "Production webhook",
    "event_types": ["payment.executed", "conversion.executed"],
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_delivered_at": null,
    "last_failure_at": null,
    "created_at": "2026-05-16T00:00:00.000Z",
    "updated_at": "2026-05-16T00:00:00.000Z"
  },
  "signing_secret": "shown once"
}

Common errors: validation_failed, limit_exceeded, idempotency_key_reuse_mismatch, insufficient_scope.

Related recipe: Verify a Webhook.