Job webhook-receiver-verified-signature-duplicate-safe · revised 11 October 2026
A webhook receiver that checks signatures and handles repeats and replays safely
One signed webhook event is accepted only with a valid signature, answered fast from a durable record, and acted on once in effect when delivered twice or replayed from a captured copy.
You might be seeing
- The endpoint accepts requests from anyone who knows its URL
- The sender reports timeouts or retries, or one event causes two emails, records or charges
- A request captured once can be sent again later and is acted on again
No passwords, keys, card details or admin invites needed to start.
What usually happened
A webhook endpoint is public, so anyone who finds the URL can post to it, and senders deliver at least once, sometimes more. A receiver that trusts every request, does slow work before answering, or has no memory of which deliveries it handled will act on forged or repeated events. Remembering a delivery by an identifier in an unsigned header does not stop a replay: a signature can cover only the body (GitHub's and Shopify's documented signatures do), so someone holding one captured valid request can change the header and be treated as new. Recording a delivery and then acting on it in two separate steps loses the event if the process stops between them. The job builds one receiver for one event type from one sender whose signature scheme is publicly documented, with a repeat key taken from the signed bytes and the work run from a durable record.
Who it’s for: A founder, operations lead or technical contact who needs one outside service to push events into their own system and cannot rely on an unauthenticated URL.
Usually starts when: A tool you use can send webhooks, but you have no receiver yet, or your current endpoint accepts any request, answers too slowly, or acts twice when a delivery is repeated.
The result: Against synthetic signed deliveries, the receiver accepts a correctly signed event and acts on it once in effect; rejects an altered body, a wrong secret and a missing signature without storing or acting on them; answers within the sender's documented time limit; treats a repeated delivery as already handled, including a captured copy whose unsigned identifier header has been changed; and loses nothing and doubles nothing when it is stopped between storing a delivery and acting on it.
Check whether this job fits
Answer these without sending secrets or customer data. Nothing is submitted unless you choose to contact us.
Checks you can run yourself
Find the signature rule
Open the sender's webhook documentation and note the header name, the algorithm and exactly which bytes are signed. Do not paste the secret anywhere.
Look for: A named header, an HMAC algorithm and a statement that the raw request body is signed. If any of these is missing, tell us.
Find where the identifier lives
In the sender's documentation or a sample delivery, note whether a unique event identifier appears inside the body, or only in a header. Do not paste a real delivery or the secret anywhere.
Look for: An event identifier inside the body is covered by the signature. An identifier only in a header is not, so the repeat key then comes from a hash of the body.
What you get
- The receiver's source code in a repository you control, with a short readme and a configuration list that names no secret values
- Automated tests covering valid, altered, wrong-secret, missing-signature, repeated, simultaneous and header-changed replayed deliveries, a stale timestamp where the sender signs one, and a stop between storing and acting
- A runbook: how to rotate the secret, how to replay a missed delivery, and what each log line means
- A written note of the repeat key, the retention period and what the receiver does not do, such as ordering guarantees across event types
Included
- One sender, one event type and one action in your system, such as creating a task or updating one record
- Signature verification over the exact received request body, using a constant-time comparison and a secret you hold in your own configuration; where the sender signs a timestamp, a delivery older than the sender's documented tolerance is rejected
- A fast acknowledgement after the verified delivery is stored in one durable step, with the action run afterwards from that stored record
- A repeat key taken from the signed bytes: an event identifier inside the body where the sender provides one, otherwise a hash of the raw body. An identifier that appears only in an unsigned header is not used as the key on its own
- Handled keys kept for a retention period agreed in writing, and automated tests using synthetic deliveries, including a stop between storing a delivery and acting on it
Not included
- Deploying to production, holding your secrets or changing your DNS, which stay with your team
- More than one sender, event type or action
- Repairing an existing endpoint whose only fault is that genuine deliveries fail the signature check: that is a separate, smaller fixed-price repair for one provider and one endpoint
- Building the sender's side, or fixing the sender's own delivery problems
- A guarantee that no event is ever lost: a reconciliation job against the sender's delivery log is a separate scope
- An action that is one-way and cannot be made safe to repeat for the same event, which forces a choice between a possible repeat and a possible loss after a crash
- Security assessment, penetration testing or compliance certification
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
A synthetic delivery signed with the test secret is accepted, stored, acknowledged and causes the agreed action once in effect.
Evidence: Test output and the single resulting record or message in the test destination.
A delivery with a body changed by one character, a delivery signed with a different secret, and a delivery with no signature header are each rejected, nothing is stored for them, and no action is taken.
Evidence: Test output with the response status for each case, the stored-delivery count of zero and the action count of zero.
Sending the same delivery twice, and twice at the same moment, causes the action once in effect and returns a success response for the repeat; a copy of the same body with a different unsigned identifier header is also treated as a repeat.
Evidence: Test output showing one effect and success responses for every copy, including the simultaneous and header-changed cases.
With the process stopped after a verified delivery is stored but before the action runs, and again after the action but before the delivery is marked done, a restart leaves exactly one effect for that delivery.
Evidence: The stop-between log for both points with the effect count after the restart.
Where the sender signs a timestamp, a delivery with a valid signature and a timestamp older than the sender's documented tolerance is rejected; the note states the retention period and, where no timestamp is signed, that a request older than it can act again.
Evidence: Test output for the stale delivery and the retention paragraph of the note.
With the downstream work artificially slowed beyond the sender's documented time limit, the receiver still acknowledges within that limit and completes the work afterwards.
Evidence: Timed test output and the completed action record.
Sign-off. You run the automated tests and review the evidence, then sign off before payment. Your team deploys the receiver and checks one live delivery under your own keys.
If it fails. If the agreed tests do not pass, you do not pay for this fixed scope. We hand over what we found and agree whether to stop or re-quote; no surprise work.
When it fits, and when we stop
It fits when
- The sender publicly documents an HMAC signature scheme, with the header name, the algorithm and the exact bytes signed
- Either the signed bytes of a delivery contain a stable event identifier, or a retry or redelivery carries the same bytes as the first attempt, as the sender's documentation or a test redelivery shows, so a repeat can be recognised from the signed bytes
- You have somewhere to run a small HTTPS endpoint under your own account (for example an existing application or a serverless function) and a durable place to store received deliveries and handled keys
- The action can be made safe to repeat for the same event key, or its result can be written together with the stored delivery in one transaction
- You can generate a test secret and send or simulate signed test deliveries without real customer data
We stop and tell you if
- The sender offers no signature, or an undocumented one, so there is nothing safe to verify
- The signed bytes hold no event identifier and two different genuine events can be byte-for-byte identical, so a replay cannot be told from a new event; we quote a different scope
- The action is one-way and cannot be made safe to repeat or written in one transaction with the stored delivery, so a crash forces a choice between a possible repeat and a possible loss
- The action would move money, delete data or message customers, and no reviewer on your side will approve it
- The only test route is production events carrying real customer data
What could go wrong
Nothing is deployed by us. Your team deploys the receiver; to reverse it, point the sender back at the old endpoint or disable the subscription, and revert the repository change. The handover lists the configuration to remove.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| Verification runs on a re-serialised body and rejects genuine deliveries or accepts altered ones. | Verify the exact received bytes before any parsing, and include tests that change whitespace and key order in the body. |
| A secret is logged, committed or sent by ordinary email. | The secret stays in your configuration store. Logs record outcomes only, and the reviewer checks the repository and logs for secret material. |
| A captured valid request is sent again with a different unsigned identifier header and is treated as a new event. | The repeat key comes from the signed bytes, not from an unsigned header. A test sends the same body with a changed header and checks that nothing is done twice. |
| The process stops after a delivery is recorded and before the action runs, so the event is lost; or after the action and before it is marked done, so the action runs again. | The delivery is stored first and the action runs from that record, so a stop before the action leaves it to be picked up on restart. The action leaves one effect for one key, so a rerun changes nothing. A test stops the process at each point and counts effects. |
| Handled keys are deleted too early, and an old captured request acts again. | The retention period is agreed and written down. Where the sender signs a timestamp, stale deliveries are rejected and the keys need to outlast only the tolerance and the sender's retries. Where it does not, a request older than the retention can act again, and the note says so. |
An independent reviewer checks the redacted before and after evidence, that every test used synthetic data, that nothing outside the agreed scope changed, and whether your authorised owner can safely reverse the change.
How we deliver
We arrange the work and independent review, then show you the result against the agreed checks. You keep authority over your systems.
- Agree the sender, the event type, the single action and how it is made safe to repeat, the repeat key, the retention period, the time limit and the checks that define done in writing
- Build synthetic deliveries from the sender's documented examples, signed with a test secret, and record the starting behaviour
- Implement verification over the exact received bytes with a constant-time comparison, rejecting before anything is stored or any other work is done; reject a stale signed timestamp where the sender provides one
- Store each verified delivery in one atomic step under its repeat key, acknowledge, and run the action afterwards from the stored record, so a repeat or a simultaneous duplicate finds the key already there
- Run the automated tests, then a manual run with altered, unsigned, repeated and header-changed deliveries and with the process stopped between storing and acting; capture the logs
- Independent review of the verification code, the repeat key, the handling of secrets and the action's side effects, then hand over the repository, runbook and notes; your team deploys
This is a one-off job, not emergency cover or a subscription. We confirm eligibility, the total price, a start window and a delivery date before you accept. Work starts only after agreed inputs, secure access, any licences and necessary permissions are in place. Platform, hosting and supplier charges are excluded unless the written quote includes them. No charge or booking is created by an enquiry.
Need to keep it working?
If events are business-critical, discuss a reconciliation check against the sender's delivery log as a separate agreed job.
Ongoing work is separately scoped and quoted: no monitoring, response-time guarantee or automatic subscription is included in this job.
Explore an ongoing engineering lane, or mention the responsibility you need in your enquiry.
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 your sender is GitHub, its documentation shows signature verification with example code in several languages, and a developer on your team may be able to follow it directly. docs.github.com
- Some senders provide an official library or tooling that verifies signatures for you; check your sender's developer pages before commissioning a build.
Questions
Which senders does this cover?
Any sender that publicly documents an HMAC signature over the request body. We confirm the scheme from its documentation before quoting, and name the sender and event in the agreement.
What stops someone replaying a request they captured?
The receiver remembers each delivery by a key taken from the signed bytes, so changing an unsigned header does not make a copy look new. Where the sender signs a timestamp, old copies are also rejected. Where it does not, a copy older than the agreed retention period can act again, and the handover note says so.
Does this make sure no event is ever lost?
No. It makes sure each delivery that arrives is checked, stored and acted on once in effect, even if the process stops part-way. Recovering events missed during an outage needs the sender's delivery log and is a separate scope.
My endpoint exists but rejects genuine events. Is this the job?
Usually not. That is a smaller repair of one existing endpoint. This job builds a receiver with a durable record and a repeat key.
Will you hold our signing secret?
No. You generate it and keep it in your configuration. We build and test with a separate test secret.
Send an enquiry
Send us
- The sender's name and a link to its public webhook and signature documentation
- The event type and the one action it should cause, in a sentence
- Where the endpoint would run, and whether a durable store for received deliveries exists
- Whether you have a receiver today and what it does wrong: no verification, slow answers, repeated actions, or only rejecting genuine events
- Do not send the signing secret, API keys, customer data or source code in the first enquiry
Later, once you agree
- A repository or code-export route you control, with no production secrets
- A test signing secret you generate, held in your own configuration
- Synthetic sample payloads, or permission to build them from the sender's documented examples
You keep the live accounts, production keys and customer records. We work only on a copy or a test route with synthetic data, through a company-controlled handoff agreed before any access; a person owns Synthetic Industry and remains accountable. Your authorised account holder approves and carries out the live change.
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 “webhook-receiver-verified-signature-duplicate-safe” as the subject.