Webhook Error Reference
Debugging a broken webhook at 2am? This reference covers every common webhook error — what causes it, how to fix it, and how to reproduce it with WebhookWhisper to verify your fix.
Unauthorized
criticalSignature verification failed. The computed HMAC does not match the header value — usually caused by using parsed JSON instead of the raw request body.
Signature Mismatch
criticalThe webhook signature in the header does not match the expected HMAC. Common causes: wrong secret, parsing body before verifying, or charset mismatch.
Webhook Timeout
highYour endpoint did not respond within the provider's timeout window (usually 3–30 seconds). The provider will retry. Respond immediately and process asynchronously.
SSL Certificate Error
criticalYour webhook endpoint's TLS certificate is invalid, expired, or self-signed. All major providers require a valid HTTPS certificate to deliver webhooks.
Endpoint Not Found
highThe webhook URL returned a 404. Either the URL path is wrong, the route is not registered, or the server is returning 404 for unrecognized paths.
Internal Server Error
highYour server crashed while processing the webhook. The provider will retry. Check your server logs for the exception — common causes include unhandled null values in the payload.
Duplicate Events
mediumReceiving the same webhook event multiple times. Providers retry on timeout or non-2xx responses. Implement idempotency using the event ID to deduplicate.
Missing Events
mediumExpected events are not arriving. Common causes: webhook not registered, wrong event types selected, IP not allowlisted, or endpoint returning errors.
The 3 Most Common Webhook Mistakes
Parsing the body before verifying the signature
HMAC signature verification requires the raw request bytes — exactly as sent. Using express.json() or body parsers before verification changes the byte sequence and breaks the HMAC. Always use express.raw({ type: 'application/json' }) for webhook endpoints.
Not responding quickly enough
Most providers timeout after 3–30 seconds. If your handler processes synchronously (database writes, API calls, emails), you will hit timeouts and get duplicate deliveries. Return HTTP 200 immediately and process the event in a background queue.
Not implementing idempotency
Providers retry on failure. If your endpoint returns 500 or times out, the same event arrives again. Without idempotency checks on the event ID, this creates duplicate orders, charges, or emails. Always deduplicate using the provider's event ID.
Debug Webhook Errors in Real Time
WebhookWhisper captures every request with full headers, body, and timing — so you can see exactly what the provider sent and reproduce the error.
Start Debugging Free