Start with the webhook’s delivery history. Compare the response status, response body, attempt count, next retry time, and delivery error before changing configuration.
Error Responses
Common Errors
400 Bad Request:
{
"error": "Webhook name cannot be empty",
"error_code": "BAD_REQUEST",
"timestamp": "2025-01-15T10:30:00Z"
}
401 Unauthorized:
{
"error": "Missing or invalid Authorization header",
"error_code": "UNAUTHORIZED",
"timestamp": "2025-01-15T10:30:00Z"
}
403 Forbidden:
{
"error": "Organization admin or owner role required",
"error_code": "FORBIDDEN",
"timestamp": "2025-01-15T10:30:00Z"
}
404 Not Found:
{
"error": "Webhook not found",
"error_code": "NOT_FOUND",
"timestamp": "2025-01-15T10:30:00Z"
}
Delivery troubleshooting
| Symptom | Check | Action |
|---|---|---|
| No attempts appear | Webhook is active and subscribed to the emitted event | Confirm configuration and query the runtime event-types endpoint |
| Signature validation fails | Raw request bytes, current secret, signature prefix, and comparison lengths | Verify the unmodified body before parsing and use constant-time comparison |
| Deliveries repeat | X-Webhook-Delivery-Id and attempt number |
Persist the delivery ID and make processing idempotent |
| Attempts time out | Receiver latency and synchronous work | Acknowledge quickly and move processing to a durable queue |
| Retries stop | Attempt count and latest response/error | Repair the receiver, then reconcile critical state through the authoritative API |
For security-sensitive failures, re-read signing and verification. For delivery guarantees and retry timing, see delivery and retries.