Webhook Error Reference

Your endpoint rejected a malformed body — parse error, missing required field, content-type mismatch. Most providers do not retry 400s, so the event is dropped.

Signature verification failed. The computed HMAC does not match the header value — usually caused by using parsed JSON instead of the raw request body.

A WAF, IP allowlist, or auth gate blocked the request before your handler ran. Common with Cloudflare bot protection or strict origin rules.

The 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.

Route exists but is registered for the wrong HTTP method. Webhooks are POST — a 405 means your handler is configured for GET, PUT, or missing OPTIONS preflight.

Body exceeded a size cap somewhere in your stack — framework parser, reverse proxy, or platform limit. Big Shopify orders and GitHub push events routinely hit this.

Body parsed but failed schema validation. Usually a strict validator rejecting an evolved provider payload, or an event type your handler did not anticipate.

A rate limiter rejected the delivery. Often self-inflicted — too-tight per-IP limits applied to provider egress IPs, or retry storms after recovery.

Unhandled exception in your handler. Provider retries on schedule, duplicate deliveries pile up. The structural fix is to ack fast and process async.

Reverse proxy could not reach your handler. Container restart, OOM kill, or app crash. Usually deploy-window blip; sometimes signal of operational fragility.

Service intentionally refused — maintenance mode, dependency unavailable, circuit breaker open. Always include Retry-After header so retries pace correctly.

Reverse proxy gave up waiting for your handler. Either the handler is too slow or the proxy timeout is too short. Webhook handlers should respond in under 100ms.

Generic HMAC verification failure. Wrong secret, parsing body before verifying, or charset mismatch. See provider-specific pages for tailored fixes.

stripe.webhooks.constructEvent throws SignatureVerificationError. Usually express.json() before express.raw(), wrong secret, or 5-minute timestamp tolerance exceeded.

X-Hub-Signature-256 verification failed. Common causes: SHA1 vs SHA256 confusion, missing sha256= prefix, body parsed before HMAC.

X-Shopify-Hmac-Sha256 mismatch. Shopify uses base64 (not hex like Stripe/GitHub) — copy-pasted Stripe verification fails 100% on Shopify.

X-Twilio-Signature mismatch. Twilio signs URL+form-params (not raw body) — most failures are URL reconstruction issues behind reverse proxies.

X-Slack-Signature mismatch. Common causes: using bot token instead of signing secret, missing v0 prefix in signed string, or body parsed before HMAC.

Your webhook endpoint's TLS certificate is invalid, expired, or self-signed. All major providers require a valid HTTPS certificate to deliver webhooks.

Source could not resolve your webhook hostname. Domain expired, DNS not propagated, missing AAAA record on IPv6-only network, or DNSSEC misconfiguration.

TCP RST from your server — application down, listening on wrong interface, firewall blocked, or port mismatch. Different from 502: no proxy is involved.

Connection established and then severed mid-request. Mid-request crash, OOM kill, idle-timeout mismatch, or reverse-proxy buffer overflow.

Your endpoint did not respond within the provider's timeout window (usually 3–30 seconds). The provider will retry. Respond immediately and process asynchronously.

Verification SDK errors saying it needs raw bytes. The body was parsed by middleware before your verification code ran. Use express.raw() on the webhook route.

Same event arriving multiple times — expected under at-least-once semantics. Implement idempotency keyed on the provider event ID; duplicates should be 200 no-ops.

Expected events are not arriving. Common causes: event type not in subscription, endpoint auto-disabled, scope mismatch, or wrong test/live environment.