v28

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-07-082940159.9 KB

Webhooks

Create a webhook

Creates a new webhook endpoint. When events occur (e.g. feedback_record.created), the Hub POSTs a signed payload to the webhook URL. If signing_key is omitted, a key is auto-generated (Standard Webhooks format, whsec_...). tenant_id is required; webhooks only receive events from that exact tenant. See WebhookDeliveryPayload for the payload structure sent to your URL.

post/v1/webhooks

Request body

urlstring uri required

URL to receive webhook POSTs. Must be an HTTP or HTTPS URL. NULL bytes not allowed.

signing_keystring

Optional. If omitted, a key is auto-generated (whsec_...). Used to sign payloads (Standard Webhooks). When provided, max 255 characters; NULL bytes not allowed.

enabledboolean

Whether the webhook is active (default true)

tenant_idstring required

Tenant/organization identifier. Required for webhook isolation; NULL bytes not allowed.

event_typesWebhookEventType[]

Event types this webhook subscribes to. Each value must be one of WebhookEventType. If empty, the webhook receives all event types.

Example request

{
  "url": "https://example.com/hub-events",
  "signing_key": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "tenant_id": "org-123"
}

Response

Created

idstring uuid required

Webhook ID (UUID)

urlstring required

URL that receives webhook POSTs

signing_keystring required

Key used to sign payloads (Standard Webhooks)

enabledboolean required

Whether the webhook is active

tenant_idstring

Tenant/organization identifier

event_typesWebhookEventType[]

Event types this webhook subscribes to (empty = all)

created_atstring date-time required

When the webhook was created

updated_atstring date-time required

When the webhook was last updated

disabled_reasonstring nullable

Read-only. Set by the system when the webhook was disabled (e.g. after 410 Gone or max delivery failures). Omitted when null.

disabled_atstring date-time nullable

Read-only. When the webhook was disabled. Omitted when null. Cleared when the webhook is re-enabled via PATCH.