A practical business guide

How to verify a webhook signature before processing an event

Set up a webhook receiver to verify requests and test that invalid deliveries cannot change your records.

Download the worksheet ↧

Verify the delivery before any write

Keep the exact request body and signature header at the endpoint that receives the webhook. Verify them with the expected provider’s verifier and that endpoint’s signing secret before parsing the event for business use. Reject missing, invalid or stale signatures before you create a task, send an email, or write a record. Once verification succeeds, check the event type and target account, then apply your duplicate handling rule.

A webhook is a request another system sends when an event happens. A signature ties the signed parts of that request to the party that holds the signing secret. It checks whether those parts changed in transit. The rules still need to say which valid events are allowed to change your records. For example, a valid delivery from a test account cannot approve a production stock change.

At the receiver, set a body size limit and preserve the provider body before any middleware normalizes it. A gateway that converts the body to a JSON object and then serializes it can change spaces, property order or escaped characters. Those changes matter even when the resulting JSON describes the same record. If the gateway cannot hand the original body through, verify at the gateway before forwarding a trusted event over an authenticated connection.

Use the rules for your endpoint

For Stripe, use the raw request body, the Stripe-Signature header and the signing secret for that specific endpoint. The Stripe CLI listener and your dashboard endpoint use different signing secrets. The Stripe verifier checks the signed timestamp against its allowed time tolerance. Keep the receiver clock synchronized and test the configured tolerance. A timestamp in a general request header provides no substitute for the provider’s signed timestamp. See Stripe’s signature troubleshooting and its webhook receiver documentation.

GitHub documents a different scheme. It puts an HMAC-SHA256 digest of the payload in X-Hub-Signature-256 with a sha256= prefix. HMAC is a message authentication code that uses a shared secret. Follow the format, use the original bytes, and use a constant-time comparison or a provider library. GitHub’s documented body signature does not authenticate a timestamp. Do not attach Stripe’s freshness rule to it. Review the GitHub verification guide and test vector.

Keep signing secrets in the server’s approved secret store. Record the endpoint label and secret version in a change record. Keep secret values, full headers and payload bodies out of ordinary logs. During a suspected bad rotation, check one synthetic delivery from the expected source before changing production configuration. If two versions must overlap, follow the provider’s documented procedure and set a removal time.

Fictional example · A dispatch task from an inventory event

In this invented example, a parts warehouse receives an inventory event and queues a task after a stock count is approved. The test body contains event DEMO-728, warehouse T-04, and quantity 12. The receiver verifies this event before checking that it came through the permitted test endpoint and that the body describes a stock-count approval for T-04.

The team sends one signed fixture, then repeats the request with the original signature but changes the quantity to 21. In a third case it keeps quantity 12 and adds a newline to the end of the body. Both altered deliveries must stop at the signature check. A valid signed event for a warehouse the workflow does not serve must stop at the business rule check. Finally the team sends the legitimate event again, with any timestamp required by the test verifier within tolerance. The expected outcome is a single dispatch task.

Acceptance cases for the fictional receiver
DeliveryExpected resultNew tasks
Original body, correct signature, expected warehouseVerify and accept1
Changed quantity or added newline with original signatureReject at signature check0
Original body signed with the wrong endpoint secretReject at signature check0
Valid signature for a warehouse outside scopeReject at business rule check0
Valid repeat of the accepted eventApply duplicate rule0

Use a separate stale signature case if your provider signs a timestamp. Generate it with the test secret and a timestamp outside the allowed window. This isolates time rejection from a wrong secret. For a concurrent duplicate test, deliver the same accepted event to two workers together. The case passes only if the actual task destination contains one new record.

Trace failed verification without opening the workflow

  1. Check the provider delivery view for the registered endpoint and delivery time. Check the receiver log for that request’s outcome category.
  2. If the header is missing, inspect forwarding rules and the HTTP route. The same app can expose different middleware on two routes.
  3. If the signature differs, compare the endpoint and environment configuration first. Replay a synthetic fixture with exactly the same bytes in a controlled test, then check whether parsing or forwarding changed the body.
  4. If freshness is the issue, check clock synchronization and the signed timestamp before changing any tolerance.
  5. After a fix, repeat both the positive and negative cases. Inspect destination state for rejected requests and duplicates. Where reliable asynchronous handling is needed, acknowledge only once the verified, allowed event is durably accepted for processing.

For reporting, record a time, endpoint label, request correlation ID, outcome category and whether a write occurred. If several invalid requests arrive, aggregate them by failure category. Keep any captured production payload out of shared troubleshooting notes.

Run this checklist before connecting production

WEBHOOK ACCEPTANCE WORKSHEET
Provider / endpoint label / environment:
Raw-body capture point and body size limit:
Signature header / verifier / signing secret version:
Signed timestamp rule, if supported:
Allowed event types and account checks:
Event identity / duplicate record / destination write:
Case | Expected verification | Expected writes | Observed writes | Evidence
Original synthetic fixture | accept | 1 |
Changed quantity and added newline | reject both | 0 |
Missing signature or wrong endpoint secret | reject both | 0 |
Stale signed timestamp, when supported | reject | 0 |
Valid event outside business scope | deny | 0 |
Valid repeat, including two concurrent deliveries | deduplicate | 0 additional |
Operator reviewing the evidence / decision date:

For the next step after authentication, use the duplicate actions guide to define the event and write keys. To discuss the receiver and its acceptance tests, bring the provider name, the intended action and a fictional payload to a fit call about workflow automation.

Put the plan to work

Start with one useful change.

Bring the process, the people involved, and a redacted example. A free 30-minute fit call can establish the next step.