FOformbricks
Webhooks

Create a webhook

Changed on

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

  • Base URL
    http://localhost:8080
  • URL
    http://localhost:8080/v1/webhooks
  • Auth
    HTTP bearer

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. U+FFFD is not allowed (it stands in for invalid UTF-8 or an unpaired surrogate).

event_typesWebhookEventType[]

Event types this webhook subscribes to. Each value must be one of WebhookEventType, listed at most once. 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.

Changes

  • ac72ae0de955Revision changes
    • warning

      changed the pattern of the request property from ^[^\x00]*$ to ^[^\x00\uFFFD]*$

    • info

      added the non-success response with the status

  • 17c77a1a3031Revision changes
    • warning

      added the new content_too_large enum value to the response property for the response status

    • warning

      added the new content_too_large enum value to the response property for the response status

    • warning

      added the new content_too_large enum value to the response property for the response status

    • warning

      added the new content_too_large enum value to the response property for the response status