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.
Field naming
Request bodies accept either snake_case or camelCase — both parse. Response bodies are
always camelCase (endpointId, eventTypes, subscriptionId), because responses are
encoded with protojson. Fields that are unset, empty, zero, or false are omitted from the
response entirely rather than sent as null — read them with a default, not a presence check.
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 eventTypes 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 externalId — your own identifier, unique
among live subscriptions in the tenant. Where a subscription reference is needed you
may supply either subscriptionId or externalId, but exactly one: sending
both, or neither, is rejected. An externalId 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 |