Skip to content

Troubleshooting

Webhooks not arriving or failing verification

Find out why webhook events don't reach your endpoint or fail signature verification: mode, subscriptions, topics, firewalls, raw body, headers and clocks.

Webhook problems come in two kinds: events never reach your endpoint, or they arrive and your code rejects the signature. Each has a short list of causes.

Events don’t arrive

The endpoint is in the other mode

Each endpoint belongs to one mode. An endpoint you created with Test Mode on receives events from test envelopes only, and one created with Test Mode off receives live events only. If you switched from a test key to a live key, register the endpoint again in live mode. See Test and live endpoints.

The endpoint isn’t subscribed to the event

An endpoint receives only the event types you selected for it. Open the endpoint under Settings › Webhooks in the Dashboard and check that the event you expect, such as envelope.completed, is in its list. See Manage webhooks.

A topic filter excludes the envelope

When an endpoint lists topics, it receives events only for envelopes that carry one of those topics. An envelope created without a matching value in topics sends that endpoint nothing. Check the envelope’s topics against the endpoint’s list. See Topic filters.

A firewall blocks the requests

If your endpoint sits behind a firewall or an allowlist, allow the IP addresses listed in Source IPs.

The endpoint isn’t reachable from the internet

SignatureAPI delivers each event as a POST request over the internet. An endpoint on localhost or a private network can’t receive them. To test on your machine, expose it with a tunnel. See Tools.

The endpoint returns an error

A delivery succeeds only when your endpoint answers with a 2XX status. Any other status, or no answer, counts as a failure and SignatureAPI retries the event for up to 48 hours. Check your server logs for errors on the webhook route, and answer quickly: do slow work, such as downloading a deliverable, in a background job after you respond.

You missed events while the endpoint was down

Events that failed for longer than the 48-hour retry window aren’t delivered again. Fetch them from List events and process them with the same handler.

Signature verification fails

SignatureAPI signs every delivery following the Standard Webhooks specification. When the check fails, the cause is almost always one of these.

The body was parsed before the check

The signature covers the exact bytes SignatureAPI sent. If your framework parses the JSON first and you re-serialize it, spacing or key order changes and the check fails. Read the raw body on the webhook route. In Express, for example, use express.raw({ type: "application/json" }) on that route only.

A header is missing

The signature is computed over webhook-id, webhook-timestamp and the body, and sent in webhook-signature. Pass all three headers to the verification library. A proxy or framework that drops or renames headers breaks the check.

The signing secret belongs to another endpoint

Each endpoint has its own signing secret, and test and live endpoints are separate endpoints. Copy the secret from the endpoint that receives the events, under Settings › Webhooks › your endpoint. See Signing secret.

The server clock is off

The verification libraries reject a webhook-timestamp more than 5 minutes away from your server’s clock. Keep the clock in sync, for example with NTP.

Debug one delivery

Paste a delivery, its headers and your signing secret into the verifier on the Webhooks page. The check runs in your browser and shows which part fails.

Events arrive more than once or out of order

Both are normal. A delivery can repeat when your endpoint processed it but the response never arrived, and events aren’t guaranteed to arrive in order. Store each event id (evt_...) and skip the ones you’ve already processed, and read the current state from the API when the order matters. See Duplicate deliveries.