Webhooks
Troubleshooting webhooks
Diagnose failures and recover without repeating business effects.
Start with delivery history and receiver event-ID logs. Confirm merchant and environment.
| Symptom | Check |
|---|---|
| No delivery | Endpoint enabled, event subscription, correct merchant; Mock does not emit events |
404 | Final POST route, deployed application, current tunnel URL |
401 / 403 | Browser-login middleware or WAF; retain webhook signature verification |
400 | Correct secret, signature, raw body, JSON, and envelope |
410 | Destination disabled; fix the receiver before re-enabling |
429 | Receiver limits and remaining delivery attempts |
5xx / timeout | Inbox availability, response latency, network and TLS |
| Delivered, but no business effect | Durable inbox and worker processing status |
| Duplicate fulfilment | Atomic inbox uniqueness and business idempotency |
Missing data.object | Signed _truncated reference; fetch through a trusted API origin |
Collect evidence
Record environment, endpoint/delivery ID, event ID, attempt time, HTTP status, and processing status. Redact secrets and customer data. Never send signing secrets or API keys in a support report.
Recover safely
- Fix the cause and verify durable acceptance with a signed test fixture.
- Check whether the business operation already completed.
- Retry failed work with the same business idempotency key.
- Verify application state, not only HTTP status.
Do not disable verification or clear the deduplication store. For network restrictions, coordinate a scoped rule with your security team; no fixed outbound IP list is promised here.
Contact support with redacted delivery IDs.