Job api-webhook-signature-verification-fails · revised 11 October 2026
Fix one webhook endpoint that rejects genuine events as unsigned
One named provider's test events pass signature verification at your endpoint, and forged or altered events are rejected. You review and release the change.
You might be seeing
- The provider's delivery log shows events failing with 400, 401 or 403 from your endpoint
- The same code passes the provider's sample check but fails on real deliveries
- Everything worked until a framework, proxy or hosting change
No passwords, keys, card details or admin invites needed to start.
What usually happened
The endpoint computes its signature over something other than the exact bytes the provider signed, for example a parsed and re-serialised body, a body altered by a proxy, a different secret for a different environment, or the wrong header, encoding or algorithm. As a result genuine events are refused, or a developer is tempted to skip verification entirely, which would let anyone post fake events.
Who it’s for: A founder or product owner whose web app receives events from one outside service (orders, repository events, form or calendar events) and whose endpoint answers genuine events with an error such as 400 or 401, or silently ignores them.
Usually starts when: A webhook was set up and appears in the provider's delivery log as failed with a signature or authorisation error, or a framework, proxy or hosting change was followed by every delivery failing the signature check.
The result: For one named provider and one endpoint, the provider's test events are accepted with a correct signature and rejected when the body, signature or secret is altered, and verification stays on. You receive the change, the test inputs and redacted evidence.
Check whether this job fits
Answer these from the provider's delivery log and your endpoint description. They do not need secrets, real event bodies or source code.
Checks you can run yourself
Compare the secret source in each environment
In the provider's webhook settings, note which endpoint address and secret belong to the failing environment. Ask your developer which environment variable the running endpoint reads. Do not paste the secret anywhere.
Look for: Whether the secret used by the running endpoint belongs to the same provider endpoint that is sending the failing deliveries. A local test tool often uses a different secret from the live endpoint.
What you get
- A pull request with the endpoint change and the tests
- A written note of the cause and the provider scheme the code now follows
- Redacted evidence of a test delivery accepted and of altered deliveries rejected
- Reversal steps and any limits found
Included
- One inbound webhook endpoint for one named provider and one signature scheme (for example an HMAC of the raw body in a header)
- Find why verification fails by comparing the exact received bytes, headers and secret source with the provider's documented scheme
- Repair how the raw body is read, which header and secret are used and how the comparison is made
- Add tests built from the provider's documented sample or a synthetic signed payload, including tampered cases
- Record redacted evidence from the provider's test delivery tool where one exists
Not included
- Building a new webhook integration, new event handlers or business logic for what the events do
- Making a repeated delivery of the same event act only once, which belongs to the webhook receiver job
- Changing provider, replaying or repairing historical events, or reconciling past data
- Payment-provider account changes, live payment handling or refund logic
- Queue, retry or scaling infrastructure beyond the single endpoint
- Reading or rotating your webhook secret: you hold and set it yourself
- Production deployment, which stays with your team
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
A test delivery signed with the test secret, using the provider's documented scheme and sample or a synthetic payload, is accepted by the endpoint with a success status.
Evidence: The test input description, the redacted signature header and the response, from the provider's test tool or the automated test.
The same payload is rejected when one byte of the body changes, when the signature changes, when the wrong secret is used and when the signature header is missing.
Evidence: Four named automated test results with their redacted inputs and rejection responses.
The diff contains no secret, verification is not conditional on an environment flag that disables it in production, and the existing tests still pass.
Evidence: The changed-file list, a secret scan of the diff and the test results.
Sign-off. You or your authorised maintainer review the tests and evidence, run one provider test delivery against your staging endpoint, sign off in writing and merge. Payment follows sign-off.
If it fails. If the provider's documented test input does not pass, or the tampered inputs are not rejected, you do not pay for this fixed scope. If the cause is the provider, a missing signing option or an environment we cannot reach safely, we explain what we found and stop. Wider work needs a new written agreement.
When it fits, and when we stop
It fits when
- The provider publishes its signature scheme and offers a test or sample delivery
- The endpoint code can run locally or in staging, and a test secret can be set that is not the production secret
- You can name the failing endpoint and the provider event that fails
- Someone on your side can change the secret in the provider's settings if a mismatch is found
- An authorised maintainer reviews and merges the change
We stop and tell you if
- The provider does not document how it signs events, or signs with a method we cannot reproduce from its documentation
- The failure only happens with live customer data or needs the production secret to reproduce
- The cause is the provider's own outage or a suspended webhook configuration
- Making the endpoint work would mean turning verification off
What could go wrong
Before merge, closing the pull request leaves the endpoint unchanged. After merge, your maintainer can revert the commit. Events refused in the meantime can be redelivered from the provider's own log if it offers that; replaying history is not part of this job.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| The fix is made by skipping or weakening verification. | Acceptance requires tampered cases to be rejected. The reviewer reads the tests and the diff for any bypass. |
| The test uses a production secret or real customer event. | Only a test secret and the provider's sample or synthetic payloads are used. If that is not possible we stop. |
An independent reviewer checks that verification is on, that the comparison is constant-time, that tampered inputs are rejected, and that no secret appears in the diff or evidence. Your maintainer reviews and merges.
What you can check
This is a new service. We have not delivered this job for a client yet.
Other ways to get this done
- If the provider publishes a verification library or sample code, your developer can use it. GitHub's webhook documentation includes working examples and test values that show the expected signature format. docs.github.com
- If your framework reads and parses the body before your handler runs, the framework's documentation on reading the raw body is the first thing to check. nextjs.org
Questions
Can I just turn verification off for now?
We will not do that. An endpoint without verification accepts forged events from anyone who finds its address. The job exists to make verification work.
Do you work with Stripe, GitHub or Shopify webhooks?
The job covers one provider whose signature scheme is documented. Tell us which and we confirm fit from its documentation before quoting.
Will this also stop one event from running twice?
No. This job repairs an endpoint that refuses genuine events. Making a repeated delivery act only once belongs to the webhook receiver job.
Will you replay the events that failed?
No. Replaying or reconciling history is a separate decision for you and the provider. Many providers can redeliver from their own log once the endpoint works.
Do you need my webhook secret?
No. You keep it. We use a test secret and the provider's sample or synthetic payloads.
Send an enquiry
Send us
- Which provider and event type fail, and the status code your endpoint returns
- The framework and hosting service the endpoint runs on, and whether a proxy or content network sits in front
- A link to the provider's documentation of its signature scheme
- Do not send the webhook secret, real event bodies containing customer data, source code or an access invitation in the first enquiry
Later, once you agree
- The endpoint source through an agreed company-controlled route, with a branch for the pull request
- A test secret and a staging endpoint address, set by you, or a way to run the provider's sample payload locally
- A redacted failed-delivery record from the provider's log
- The name of the person who reviews and merges
You own the endpoint, the provider account and the webhook secret. We work on a branch or copy through a company-controlled identity, never a personal login, using a test secret and synthetic or provider-sample payloads. Your team sets production secrets and deploys.
Email fallback: open your mail app
If website submission is unavailable, review and send the fallback email yourself. An email fallback is not a website receipt. Or write to hello@syntheticindustry.ai with “api-webhook-signature-verification-fails” as the subject.