From reading to action
A practical path through this guide.
Select a step to explore what to do and why it matters.
Preserve original bytes
Read the request in the form required by the signing scheme.
Webhook signature verification checks whether a request matches the sending provider's authentication scheme. A valid signature is necessary for many integrations, but it does not validate the business meaning of the event. Verify authenticity before accepting work, then validate the payload separately.
Start with the exact request bytes
Many signature schemes depend on the original request body. Parsing JSON and serializing it again can change whitespace or ordering. Use the provider's supported verification library and the raw body format it expects rather than inventing a compatible-looking calculation.
Keep test and production endpoint secrets separate. A frequent diagnostic mistake is checking a production request against a local development secret. Record the environment and endpoint identifier in operational notes without exposing the secret value.
Diagnose failures systematically
Check whether middleware consumed or altered the body, whether the correct signing secret is loaded, and whether timestamp validation is affected by clock drift. Examine the provider's delivery log to confirm which endpoint actually received the request.
Never resolve a production signature failure by permanently disabling verification. Reproduce the issue with a provider test event and a sanitized local fixture. Avoid copying a real signed customer payload into a shared chat or public issue.
Keep authentication and processing separate
After verification, check the event type, required identifiers, account context, and supported version. Ignore unsupported event types deliberately rather than assuming every signed request should trigger an action. A provider can legitimately send events outside your workflow's intended scope.
Persist accepted work and deduplicate using a stable identifier. Signature checks do not prevent a legitimate event from being delivered more than once. If you operate multiple connected customer accounts, include the account boundary in routing and storage keys.
Verify the rejection paths
- A modified body must fail verification.
- A request signed with another environment's secret must fail.
- A valid event must reach the intended account only.
- A repeated valid event must not repeat the business action.
- A malformed payload must produce a controlled response without leaking secrets.
Document the credential rotation procedure and how overlapping old and new secrets are handled if the provider supports that transition. After rotation, verify a real test delivery before removing the previous configuration.
Further reading
Follow the provider-specific details in Stripe's signature verification documentation. Related guidance: idempotent workflows.
A few practical answers
Frequently asked questions
Why can a valid webhook signature fail after JSON parsing?
Some signatures depend on the exact original request bytes. Parsing and serializing can change whitespace or ordering; use the provider-supported verifier and correct raw body.
Does a verified webhook signature prevent duplicate actions?
No. Verification establishes authenticity under the signing scheme. Validate event type and account context separately, then deduplicate repeated valid deliveries before business writes.
