API BaaSWebhooks

Create webhook subscription

Creates a new webhook subscription for the current tenant. Specify the URL to receive events and optionally filter by event types.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
urlstringRequiredformat: "uri"
URL to receive webhook events.
eventTypeslist of stringsOptional
Event types to subscribe to. If empty, subscribes to all events.
authTypeenumOptionalDefaults to NONE

Authentication applied to webhook delivery. HMAC signs each request with secret in the X-Signature header; NONE uses the platform default signature. Any other value is rejected.

Allowed values:
secretstringOptional

Secret used for HMAC signing. Required when authType is HMAC.

accountIdstringOptional
Binds the subscription to a single account: it then receives only that account's events. Omit for a tenant-wide subscription (every account, the historical behaviour). Not editable afterwards. A credential restricted to specific accounts MUST provide it (`422 account_id_required`) and may only point at accounts it reaches (`403 forbidden`).

Response

Webhook subscription created.
subscriptionIdstring
Unique subscription identifier.
tenantIdstring
Tenant that owns this subscription.
urlstringformat: "uri"
URL that receives webhook events.
activeboolean
Whether the subscription is active.
eventTypeslist of stringsOptional
Event types this subscription receives.
authTypeenumOptional
Authentication applied to delivery.
hmacSecretSetbooleanOptional
Whether an HMAC key is stored. The key itself is never returned by any endpoint.
createdAtdatetimeOptional
updatedAtdatetimeOptional
accountIdstring or nullOptional

Account this subscription is bound to. null means tenant-wide: it receives every account’s events.

Errors

400
Bad Request Error
500
Internal Server Error