Webhook APIs
Register HTTPS endpoints, subscribe them to events and inspect or retry deliveries.
Use an authorized backend sk_… key in X-API-Key; these configuration operations do not need an end-user identity. A console JWT belongs to the separate console surface. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id are not an authorization mechanism. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Endpoints and subscriptions
An endpoint is your receiving URL; a subscription selects its events. Supplying eventTypes during endpoint creation also attempts a subscription, but the two writes can partially succeed. Reconcile before retrying. The current platform permits one live subscription per endpoint and rejects a second. Replacement by delete-then-create has a delivery gap; temporary overlap requires a separately created endpoint, receiver deduplication and a qualified cutover.
Subscription references accept exactly one of subscriptionId or externalId where offered. An external ID is unique among live subscriptions in its current scope and may be reused after deletion; do not treat a reused alias as the original subscription’s immutable identity.
Provider cursor traversal can produce estimated totals until exhausted. Re-queue acceptance is not proof of successful delivery or business processing.
Related guide: Webhooks
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Authentication
- API Key: apiKeyAuth
- HTTP: Bearer Auth
Authorized tenant backend secret key (sk_…). No end-user identity is needed for these tenant/project configuration operations. Keep the key out of client apps; authorization and provisioning still apply.
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 |
📄️ Event catalog and delivery
event-catalog}
🗃️ Event payloads
6 items
📄️ Overview
Register HTTPS endpoints, subscribe them to events and inspect or retry deliveries.
🗃️ Endpoints
9 items
🗃️ Models
11 items
Document ID: DOC-IN-webhooks-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-IN-webhooks-api-overview#overview |
| JSON conventions | DOC-IN-webhooks-api-overview#json-conventions |
| Authentication | DOC-IN-webhooks-api-overview#authentication |
| Endpoints and subscriptions | DOC-IN-webhooks-api-overview#endpoints-and-subscriptions |
| Addressing Subscriptions | DOC-IN-webhooks-api-overview#addressing-subscriptions |