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.
Related
- Webhooks: setup, retries and verification.
- List events: fetch events you missed.
- Troubleshooting email delivery: when a recipient event shows a bounce.