Webhook APIs
Outbound webhooks — register endpoints, subscribe them to event types, and inspect or retry deliveries. All operations are scoped to the authenticated tenant.
All endpoints use POST /api/v1/webhooks/<method> with a JSON request body.
Endpoints and subscriptions
An endpoint is a URL you own. A subscription binds an endpoint to a set of
event types. Create the endpoint first, then subscribe it — or pass event_types on
create-endpoint to do both in
one call.
Keep one subscription per endpoint. Creating a second subscription on the same endpoint double-delivers every matching event.
To change what an endpoint receives, delete the existing subscription and create a
replacement — do not add a second one. There is currently no update-subscription
route exposed, so delete-then-create is the supported path. Events published in the
gap between the two calls are not delivered to that endpoint.
Addressing subscriptions
create-subscription accepts an optional external_id — your own identifier, unique
among live subscriptions in the tenant. Where a subscription reference is needed you
may supply either subscription_id or external_id, but exactly one: sending
both, or neither, is rejected. An external_id is released for reuse once its
subscription is deleted.
Authentication
- API Key: apiKeyAuth
- HTTP: Bearer Auth
Your API key. sk_… for backend-to-backend calls, pk_… for client apps.
Never valid on its own — see the combinations under Security below.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
The end user's own JWT, issued by the OIDC provider configured on the
publishable key. Required alongside a pk_… key, and supplies the user
identity in place of X-On-Behalf-Of.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |