Webhook ingestion
v1
stable
Ingest a webhook delivery
Authenticate an inbound delivery, deduplicate it by a stable delivery key, and enqueue the selected active workflow. A 202 response means accepted, not completed.
POST
/api/v1/webhooks/{token}
Access and behavior
- Required scope
- webhooks
- Authentication
- Selected service-account bearer token; optional API-key or HMAC sender verification
- Idempotency
- seven-day delivery deduplication
- Operation ID
- ingestWebhookDelivery
Request headers
| Header | Presence | Description |
|---|---|---|
| Authorization | Required | Short-lived service-account bearer token. |
| Idempotency-Key | Optional | Stable sender delivery identifier. Repeated deliveries are acknowledged as duplicate during the seven-day retention window. |
| Content-Type | Required | Request document media type. |
Parameters
token
path · Required
string
Opaque token from the active webhook trigger URL.
Request body
application/json
Schema: object
· Required
request.json
{
"event": "order.created",
"order_id": "ord_123"
}Success response
202
The delivery was accepted or recognized as a duplicate.
- Media type
- application/json
- Schema
- WebhookAccepted
Errors and retries
Keep x-request-id
from failed responses. Retry only rows marked retryable, and obey
Retry-After
when present.
| Status | Code | Recovery | Meaning |
|---|---|---|---|
| 401 | missing_credentials | Do not retry unchanged | The bearer token is missing, invalid, or expired. |
| 401 | unauthorized | Do not retry unchanged | The selected service account, organization, or connector authentication is invalid. |
| 403 | insufficient_scope | Do not retry unchanged | The selected service account lacks the webhooks scope. |
| 404 | not_found | Do not retry unchanged | The active trigger was not found. |
| 413 | payload_too_large | Do not retry unchanged | The body exceeds the configured limit (1 MiB by default). |
| 429 | rate_limited | Retry after guidance | The delivery exceeded its rate window; wait for Retry-After. |
| 422 | processing_failed | Do not retry unchanged | The delivery failed stable workflow or payload validation. |
| 422 | unsupported_trigger_authentication | Do not retry unchanged | The trigger uses a connector authentication mode that conflicts with bearer authentication. |
| 503 | temporarily_unavailable | Retry after guidance | A transient processing dependency failed; retry after Retry-After. |
Related guides
Send your first webhook delivery
Configure an active webhook workflow, send one idempotent JSON delivery, and verify the accepted run through JSON:API.
Webhook deduplication, retries, and troubleshooting
Choose stable delivery IDs, interpret accepted duplicates, and retry only transient webhook-ingestion failures.