Testing and troubleshooting webhooks
When to use this guide: You need to prove an endpoint works, inspect delivery history, or fix a Webhooks failure. Inbound Sources paste-URL issues belong in Sources and delivery and SEP setup guides.
How to test OutboundSync webhooks
Section titled “How to test OutboundSync webhooks”- Register the webhook and store the signing secret (Setting up webhooks).
- Implement signature verification (Payloads and signatures).
- Call
POST /api/v1/webhooks/:id/test(write scope) — returns202with{ "eventId": "osevt_…" }and queues atest.pingdelivery. - Confirm your endpoint returned
2xxand thatGET /api/v1/webhooks/:id/deliveriesshowsSUCCEEDED.
You can also send test and inspect deliveries under Dashboard → Webhooks, or from Try the API when OpenAPI lists these paths.
Replay a delivery
Section titled “Replay a delivery”POST /api/v1/webhooks/:id/deliveries/:deliveryId/replay creates a new delivery linked via replayOfDeliveryId. Use this after fixing your endpoint or after an auto-disable incident.
No active sendable events
Section titled “No active sendable events”If you never receive sync.failed / sync.recovered, confirm the webhook is isActive, enabledEvents includes those types (or is empty), and that a real healthy↔failing transition occurred for a source×connection. Use GET /api/v1/events to see whether events were emitted without a successful delivery.
403 forbidden
Section titled “403 forbidden”Common causes:
- Webhooks not enabled (
canUseWebhooks) - Connection-scoped key used on
/api/v1/webhooks* - Missing
writescope on a mutation
See Errors and rate limits and Creating API keys.
Signature verification fails
Section titled “Signature verification fails”- Verify against the raw body bytes.
- Confirm you stored the latest secret after create or rotate.
- Reject only after a constant-time compare; check clock skew against
t=(for example a 5-minute window).
HTTPS URL rejected
Section titled “HTTPS URL rejected”OutboundSync accepts HTTPS only and rejects private, loopback, and link-local targets (including DNS that resolves to private space). Use a publicly reachable HTTPS endpoint.
Webhook auto-disabled
Section titled “Webhook auto-disabled”Twenty consecutive DEAD deliveries disable the endpoint. Fix the handler, then PATCH { "isActive": true } or re-enable in the dashboard. Optionally replay recent dead deliveries.
