Skip to content

Docs / Guides

Signatures

Add a provider's signing secret to an endpoint and every webhook shows whether its signature is valid, and if it isn't, why, so you can find the bug in your own verification code.

Add the signing secret

  1. On the endpoint's page, click Settings and find Signature checks.
  2. Pick the Provider. If the latest webhook looks signed, the page names the provider it detected.
  3. Paste the Signing secret, like Stripe's whsec_…, and click Check signatures.

The secret is stored encrypted and shown masked afterwards. Leave the field empty to keep it, or click Remove secret to stop checking. Signature checks work on every plan.

When a webhook looks signed but the endpoint has no secret yet, the event says which provider signed it, with a link to add the secret.

Supported providers

Provider Header checked Where to find the secret
Stripe Stripe-Signature The webhook endpoint's page in Stripe's dashboard. Test and live mode have different secrets
GitHub X-Hub-Signature-256 The secret set on the webhook in the repository's or organization's settings
Shopify X-Shopify-Hmac-Sha256 The app's client secret, or for webhooks made in the admin, the key under Settings → Notifications
Slack X-Slack-Signature The Signing Secret under Basic Information, not the verification token or a bot token
Standard Webhooks (Svix, Resend, Clerk and others) Webhook-Signature The endpoint's signing secret, starting with whsec_

Read the result

Each event shows the check above its body, open when something is wrong:

Result Means
Valid signature Signed with this secret over the raw body, as the provider sends it
Signature doesn't match The secret doesn't produce this signature. The explanation says why, when it can tell
Valid, but too old The signature matches, but it was made more than 5 minutes before the webhook arrived. Provider libraries reject these to stop replays
Not signed The signature header is missing or incomplete, so the sender isn't signing

Below the result, a table shows the Header it read, What's signed (for Stripe, the timestamp, a dot and the raw body), the signature Received, and the one Expected with your secret. Compare "Expected" with what your own code computes: if they differ, your code is signing different bytes or using another secret.

Why verification fails

The usual causes, most of which the debugger names for you:

  • Spaces or a line break around the secret. Pasted from a terminal or a password manager. Trim it.
  • Stripe's secret without its whsec_ prefix. Stripe signs with the whole secret, prefix included.
  • Test and live secrets mixed up. Each Stripe endpoint, and each mode, has its own secret.
  • A parsed body. Your framework parsed the JSON and you verified the re-encoded body, with different spacing or key order. Verify the raw request body before parsing it.
  • An old timestamp. Stripe, Slack and Standard Webhooks sign a timestamp. Resending a webhook later fails the same way, so send a fresh one.

Example: your GitHub handler rejects every webhook with "signature mismatch". The event shows Valid signature, so the secret is right and the provider signed correctly: your code is checking a body it parsed first. You switch to the raw body and it passes.

Signed test events

On Pro and above, you can send a realistic sample signed with your own secret, so your verification runs exactly as it would in production, without a real order or payment.

  1. On the endpoint's page, click Send test event.
  2. Pick the provider and event type (listed below).
  3. Enter the Signing secret your app verifies with. If the endpoint has a saved secret for that provider, it's used unless you enter another; a secret entered here isn't stored.
  4. Edit the Body if you like: it's signed exactly as sent.
  5. Under Send to, pick one of the endpoint's destinations, any public URL, or your tunnel while whq listen runs, and click Sign and send.
Provider Event types
Stripe checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.created, payment_intent.succeeded, charge.refunded
GitHub push, pull_request.opened, issues.opened, ping
Shopify orders/create, orders/paid, customers/create, app/uninstalled

Each sample gets fresh ids and timestamps. The test shows up in the endpoint's events marked Test event, with your server's answer in its deliveries, and it doesn't count towards your plan's events.

Signatures and replays

A replayed webhook keeps the provider's signature headers, so your app checks it as before. Two things to know:

  • If you change the body with Edit and send, the signature no longer matches. Use a signed test event to test a changed body with a valid signature.
  • For providers that sign a timestamp (Stripe, Slack, Standard Webhooks), a replay more than 5 minutes after the original is rejected by their libraries as too old. GitHub and Shopify don't sign a timestamp.

The event's check is always made against the raw body and the time it first arrived, so it stays correct later. See Replay.