---
title: "Webhooks not arriving or failing verification"
description: "Find out why webhook events don't reach your endpoint or fail signature verification: mode, subscriptions, topics, firewalls, raw body, headers and clocks."
canonical: "https://signatureapi.com/docs/troubleshooting/webhooks"
source: "https://signatureapi.com/docs/troubleshooting/webhooks.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:06:40Z"
---

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

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/webhooks#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](https://signatureapi.com/docs/dashboard/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](https://signatureapi.com/docs/api/webhooks#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](https://signatureapi.com/docs/api/webhooks#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](https://signatureapi.com/docs/api/webhooks#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](https://signatureapi.com/docs/api/resources/events/all) and process them with the same handler.

## Signature verification fails

SignatureAPI signs every delivery following the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) 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](https://signatureapi.com/docs/dashboard/webhooks#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](https://signatureapi.com/docs/api/webhooks#authentication) 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](https://signatureapi.com/docs/api/webhooks#duplicate-deliveries).

## Related

- [Webhooks](https://signatureapi.com/docs/api/webhooks): setup, retries and verification.
- [List events](https://signatureapi.com/docs/api/resources/events/all): fetch events you missed.
- [Troubleshooting email delivery](https://signatureapi.com/docs/troubleshooting/email-delivery): when a recipient event shows a bounce.
