Go back to dialerseat.comsales@dialerseat.com
Guide

Webhook signature verification failed? Find the cause

A webhook signature fails when the bytes you hash differ from the bytes the sender signed, or the key differs. Most often a framework parsed the JSON body before your check, the secret is from the wrong environment, or the digest is compared as hex when the sender used base64. Verify against the raw body, with the endpoint's own secret, in the sender's encoding, then compare in constant time.

Checked 2026-11-15 against the sources linked at the end.

The seven causes, most common first

  • The body was parsed or changed. Hash the raw bytes exactly as they arrived. JSON middleware that parses and re-serializes reorders keys and strips whitespace, and the signature no longer matches.
  • The wrong secret. Test and live endpoints, a CLI forwarder and a dashboard endpoint each have their own. Print the secret your code loads and check for a trailing space or newline.
  • The wrong encoding. Some senders send a hex digest, some base64. Comparing a base64 header with a hex digest never matches.
  • The wrong signed string. Some schemes sign the body alone; others sign a timestamp, a dot and the body, or the full URL plus sorted parameters. Hash the same string the sender documents.
  • The timestamp is outside your tolerance. A clock that has drifted, or a retry checked against a tight window, fails even with a correct digest.
  • The header was read wrong. Strip a prefix such as sha256=, read every signature in the header when there are several, and accept fields you do not know.
  • A proxy changed the URL or body. For schemes that sign the URL, a load balancer that rewrites the host, scheme or port, or decodes and re-encodes the query, breaks the match.

How five senders sign

SenderHeaderAlgorithm and encodingWhat is signed
StripeStripe-Signature (t=…, v1=…)HMAC-SHA256, hexThe timestamp, a dot, and the raw body
GitHubX-Hub-Signature-256 (sha256=…)HMAC-SHA256, hexThe payload body, as UTF-8
ShopifyX-Shopify-Hmac-SHA256HMAC-SHA256, base64The raw request body, keyed with the app's client secret
TwilioX-Twilio-SignatureHMAC-SHA1, keyed with the auth tokenThe webhook URL plus the POST parameters sorted alphabetically
DialerSeatDialerSeat-Signature (t=…, v1=…)HMAC-SHA256, hexThe timestamp, a dot, and the raw body; older than 5 minutes is rejected

Each row is from that sender's own documentation, linked below. Use the sender's library where it offers one: Twilio's page tells you not to write your own validation.

Getting the raw body

  • Express: register the webhook route with express.raw({ type: 'application/json' }) before any app.use(express.json()); Stripe's guide puts the webhook route first for this reason.
  • Next.js App Router: read await request.text() and verify that string before JSON.parse.
  • Flask: request.get_data() returns the bytes before any parsing.
  • PHP: file_get_contents('php://input') returns the body as sent.

Check one delivery by hand

Paste the secret, the signature header and the raw body into the webhook signature checker on this site. It recomputes the HMAC in your browser and shows the expected value beside the one received, so you can tell a body problem from a secret problem in one try. Nothing is sent anywhere.

Then compare in constant time (crypto.timingSafeEqual in Node, hmac.compare_digest in Python, hash_equals in PHP), never with ==, and process each event id once, because senders retry.

Related: webhook signature checker, HMAC generator, webhooks in the docs and idempotency.

Sources


More: the developer FAQ, the comparisons, Answering machine detection (AMD), explained for developers, Salesforce Open CTI retirement: what it means, Do-not-call API: what the national registry offers, Moving from VICIdial's API to an embedded dialer, A click-to-call button in your CRM, Your own UI on the dialer, with DialerSeat.connect, A live status board for managers, or the quickstart, free in sandbox mode.