# Webhooks ## List **get** `/v1/webhooks` Lists webhook endpoints with optional filters and pagination ### Query Parameters - `cursor: optional string` Omit for the first page. For the next page, use the exact value from the previous response's next_cursor. Opaque (base64-encoded); keyset pagination. - `enabled: optional boolean` Filter by enabled status - `limit: optional number` Number of results to return (max 1000) - `tenant_id: optional string` Filter by tenant ID. NULL bytes not allowed. ### Returns - `data: array of object { id, created_at, enabled, 6 more }` List of webhooks (signing_key omitted for security) - `id: string` Webhook ID (UUID) - `created_at: string` When the webhook was created - `enabled: boolean` Whether the webhook is active - `updated_at: string` When the webhook was last updated - `url: string` URL that receives webhook POSTs - `disabled_at: optional string` Read-only. When the webhook was disabled. Omitted when null. - `disabled_reason: optional string` Read-only. Set by the system when the webhook was disabled. Omitted when null. - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` Event types this webhook subscribes to (empty = all) - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `tenant_id: optional string` Tenant/organization identifier - `limit: number` Limit used in query - `next_cursor: optional string` Opaque cursor for the next page (keyset paging). Present only when there may be more results. Use as the cursor query param for the next page. - `offset: optional number` Offset used in query (present when offset-based; omitted when using cursor) - `total: optional number` Total count matching filters (present when offset-based; omitted when using cursor) ### Example ```http curl http://localhost:8080/v1/webhooks \ -H "Authorization: Bearer $HUB_API_KEY" ``` ## Create **post** `/v1/webhooks` 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_...). See WebhookDeliveryPayload for the payload structure sent to your URL. ### Body Parameters - `url: string` URL to receive webhook POSTs. Must be an HTTP or HTTPS URL. NULL bytes not allowed. - `enabled: optional boolean` Whether the webhook is active (default true) - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` Event types this webhook subscribes to. Each value must be one of WebhookEventType. If empty, the webhook receives all event types. - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `signing_key: optional string` Optional. If omitted, a key is auto-generated (whsec_...). Used to sign payloads (Standard Webhooks). When provided, max 255 characters; NULL bytes not allowed. - `tenant_id: optional string` Tenant/organization identifier. NULL bytes not allowed. ### Returns - `id: string` Webhook ID (UUID) - `created_at: string` When the webhook was created - `enabled: boolean` Whether the webhook is active - `signing_key: string` Key used to sign payloads (Standard Webhooks) - `updated_at: string` When the webhook was last updated - `url: string` URL that receives webhook POSTs - `disabled_at: optional string` Read-only. When the webhook was disabled. Omitted when null. Cleared when the webhook is re-enabled via PATCH. - `disabled_reason: optional string` Read-only. Set by the system when the webhook was disabled (e.g. after 410 Gone or max delivery failures). Omitted when null. - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` Event types this webhook subscribes to (empty = all) - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `tenant_id: optional string` Tenant/organization identifier ### Example ```http curl http://localhost:8080/v1/webhooks \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $HUB_API_KEY" \ -d '{ "url": "https://example.com/hub-events", "signing_key": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "tenant_id": "org-123" }' ``` ## Retrieve **get** `/v1/webhooks/{id}` Retrieves a single webhook endpoint by its UUID. signing_key is omitted for security. ### Path Parameters - `id: string` ### Returns - `id: string` Webhook ID (UUID) - `created_at: string` When the webhook was created - `enabled: boolean` Whether the webhook is active - `updated_at: string` When the webhook was last updated - `url: string` URL that receives webhook POSTs - `disabled_at: optional string` Read-only. When the webhook was disabled. Omitted when null. - `disabled_reason: optional string` Read-only. Set by the system when the webhook was disabled. Omitted when null. - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` Event types this webhook subscribes to (empty = all) - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `tenant_id: optional string` Tenant/organization identifier ### Example ```http curl http://localhost:8080/v1/webhooks/$ID \ -H "Authorization: Bearer $HUB_API_KEY" ``` ## Update **patch** `/v1/webhooks/{id}` Updates specific fields of a webhook endpoint ### Path Parameters - `id: string` ### Body Parameters - `enabled: optional boolean` Enable or disable the webhook - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` New list of event types (use empty array to clear). Each value must be one of WebhookEventType. - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `signing_key: optional string` New signing key. NULL bytes not allowed. - `tenant_id: optional string` Omit or send null to leave unchanged. Send empty string to clear (store as null). - `url: optional string` New webhook URL. Must be an HTTP or HTTPS URL. NULL bytes not allowed. ### Returns - `id: string` Webhook ID (UUID) - `created_at: string` When the webhook was created - `enabled: boolean` Whether the webhook is active - `updated_at: string` When the webhook was last updated - `url: string` URL that receives webhook POSTs - `disabled_at: optional string` Read-only. When the webhook was disabled. Omitted when null. - `disabled_reason: optional string` Read-only. Set by the system when the webhook was disabled. Omitted when null. - `event_types: optional array of "feedback_record.created" or "feedback_record.updated" or "feedback_record.deleted" or 3 more` Event types this webhook subscribes to (empty = all) - `"feedback_record.created"` - `"feedback_record.updated"` - `"feedback_record.deleted"` - `"webhook.created"` - `"webhook.updated"` - `"webhook.deleted"` - `tenant_id: optional string` Tenant/organization identifier ### Example ```http curl http://localhost:8080/v1/webhooks/$ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $HUB_API_KEY" \ -d '{ "signing_key": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "tenant_id": "org-123", "url": "https://example.com/hub-events" }' ``` ## Delete **delete** `/v1/webhooks/{id}` Permanently deletes a webhook endpoint. It will no longer receive events. ### Path Parameters - `id: string` ### Example ```http curl http://localhost:8080/v1/webhooks/$ID \ -X DELETE \ -H "Authorization: Bearer $HUB_API_KEY" ```