Webhooks API
Inspect webhook delivery logs, replay dead-lettered deliveries, send test events, and connect signed events to product state.
The Webhooks API supports webhook operations around delivery health. Use it alongside your webhook handler: the handler verifies and processes events, while the API helps you test delivery, inspect failures, and replay dead-lettered deliveries where supported.
Endpoint map
| Method | Path | Purpose | Notes |
|---|---|---|---|
GET | /webhooks/deliveries | List your outbound webhook delivery log. | Partner-scoped; most recent first; useful for retries and dead letters. |
POST | /webhooks/deliveries/{id}/replay | Requeue a dead-lettered delivery. | Only for your own dead-lettered deliveries. |
POST | /webhooks/test | Enqueue a synthetic webhook.test event. | Use to test endpoint reachability and signature verification. |
Delivery APIs are operational tools. They do not replace raw-body signature verification or idempotent event handling.
Delivery object signals
| Field | Use it for |
|---|---|
id | Delivery record id for replay/support. |
event_id | Event dedupe and traceability. |
event_type | Handler routing and support triage. |
target_url | Confirm the delivery target. |
status | Pending, delivered, retrying, dead-lettered, or equivalent state. |
attempts | Retry count and operational health. |
last_response_status | Last HTTP status returned by your endpoint. |
last_error | Last delivery error summary. |
next_attempt_at | When retry is scheduled. |
delivered_at | Successful delivery timestamp. |
List deliveries
curl -X GET https://gate-api-sandbox.0bit.app/v1/webhooks/deliveries \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Use filters such as status and pagination where supported. Do not expect to see another partner's deliveries, raw private payloads, or provider internals.
Replay a dead-letter
curl -X POST https://gate-api-sandbox.0bit.app/v1/webhooks/deliveries/wd_test_123/replay \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 00000000-0000-4000-8000-000000000123" \
-d '{}'Replay should requeue the same delivery for another attempt. Your webhook handler must dedupe by event id so replay cannot double-fulfill an order or double-credit a balance.
Send a test event
curl -X POST https://gate-api-sandbox.0bit.app/v1/webhooks/test \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 00000000-0000-4000-8000-000000000123" \
-d '{}'Use a test event during setup, after rotating webhook secrets, after changing domains, and before switching a flow to live mode.
Debugging delivery failures
| Symptom | Likely cause | Next step |
|---|---|---|
401 or 403 from your endpoint | Your endpoint requires app auth before webhook verification. | Exempt webhook route from user auth; rely on signature verification. |
400 invalid signature | Wrong webhook secret or parsed body. | Check environment secret and raw-body configuration. |
| Timeout | Handler doing too much synchronous work. | Persist and enqueue downstream jobs. |
Repeated 5xx | App error after event receipt. | Inspect logs by event id and request id. |
| Dead-lettered delivery | Retries exhausted. | Fix endpoint, then replay. |