Two Identical Events Are One Event

Any system that sends webhooks will eventually send the same one twice. Not because it is badly built — because it lost the connection while waiting for your answer and has no way to know whether you acted on the message before the wire went quiet. Retrying is the correct behaviour for the sender. Which means deciding what a duplicate means is not an edge case for the receiver; it is part of the contract, and it is the part almost nobody writes down.

The sender can tell you, and usually does not

The clean arrangement is that every event carries a unique reference of the sender's choosing. Two requests with the same reference are the same event; two with different references are different events. It is unambiguous, it is cheap, and there is a widely used header for it.

This endpoint reads that header, under either of the two names it commonly travels as. When it is there, it is used, and the question is settled by the sender who actually knows the answer.

The rest of this post is about what happens when it is not there, which is most of the time, because the systems people want to connect are usually a workflow tool or a script rather than a payment provider with a specification.

With no reference, the message is the reference

The fallback is to derive the reference from the credential and the exact bytes of the body. Same key, same payload, same reference.

That is a genuinely good default, and it has a consequence that surprises people the first time they meet it: two byte-identical messages are one message, however far apart they arrive. There is no window in this rule. A payload sent this morning and sent again unchanged next month resolves to the same reference.

Whether that is what you want depends entirely on the message. For anything carrying its own identity — an order number, a payment reference, a document id — it is exactly right, because a genuine second event about the same thing will differ somewhere. For a message with no distinguishing content, such as a bare heartbeat that says the same sentence every hour, the second one is treated as a repeat of the first.

The fix for that is one line at the sender: include a timestamp, a counter or an identifier in the payload, or send the reference header. A message that is meant to be distinguishable should say something that distinguishes it, which is a reasonable thing to ask of a sender and a much better rule than a receiver guessing at how long two identical messages should be considered different.

Seen is not finished

Now the part that is easy to get subtly wrong, and the reason this section exists.

The obvious implementation of replay protection is: look for the reference; if it is there, this is a duplicate, so stop. That is one condition, it reads as complete, and it is wrong in a way that only shows up on a bad day.

The record is written when the request arrives, before the work is done. So a request that arrived and then did not finish — the process was restarted, the database went away for four seconds, a deployment landed mid-flight — leaves a record behind with no result attached to it.

Under the one-condition rule, the sender's retry then finds that record, concludes the event has already been handled, and returns success. The event never happened. Nothing failed, nothing was logged as an error, and the sender was told everything was fine.

The worst kind of duplicate protection is the kind that also protects you from the one delivery that mattered.

So the check asks two things: has this reference been seen, and did the request that carried it get as far as producing a result. A record with no result is treated as unfinished business, and the retry is allowed through to do the work.

That is the correct direction for this endpoint. A retry that does the work twice is a visible, fixable problem; a retry that silently confirms work nobody did is neither.

What a replay gets back

A confirmed duplicate does not get a fresh response. It gets the stored one — the same status and the same body the original request produced — plus a header saying so.

This matters more than it sounds. If the original call created something and returned its identifier, the retry hands back that same identifier rather than a null or a new one. The sender cannot tell whether it was the first or the fourth attempt except by reading the header, and either way it ends up holding a reference to the thing that actually exists.

The header is there for the people debugging, not for the machines. It answers did my retry do anything without anybody having to reason about it from timestamps.

Two halves, and either one is optional

An accepted event can do two separate things, and a single request may do one, the other, or both.

1. A message becomes a notification

   Where the payload carries a message, an in-app notification is created — which then fans out to whichever channels the workspace has connected, so an event from an external system can arrive as a chat message or an SMS without knowing anything about either.

2. An event name triggers workflows

   Where the payload names an event, matching workflows are run with the supplied data. That work is queued rather than done inline, because a workflow can itself call out to other systems and the caller should not be holding a connection open while it does.

3. Neither one is refused

   The validation requires a message unless an event is named, so a request that would do nothing at all is rejected at the door rather than accepted and quietly discarded.

That last one is the small decision worth copying. An endpoint that accepts a payload it cannot act on is the most confusing possible outcome for whoever is setting it up: the response says success, the logs are clean, and nothing appears anywhere.

Why the answer is accepted rather than done

The response is a status that means accepted, not one that means completed, and the difference is honest rather than pedantic.

The notification half really has been done by the time you get an answer. The workflow half has been handed to a queue, and it has three attempts and a couple of minutes to work in. Reporting completed would be a claim about work that has not started.

The body says which of the two halves happened: the identifier of the notification if one was created, and whether workflows were queued. A sender that reads the body knows exactly what it bought, rather than inferring it from a status code.

What is in place

Three positions held on purpose

• Doing the work twice beats confirming work nobody did. Where the two failure modes conflict, an interrupted request is allowed to be retried, because a duplicate is visible and a silent confirmation is not.
• A duplicate gets the original answer, not a fresh one. Replaying the stored response means a retry ends up holding the same identifier as the call that succeeded, which is what makes a retry safe for the sender to write.
• Distinguishing two messages is the sender's job. Deriving the reference from the payload is honest about what it can know, and the alternative — a receiver inventing a window in which identical messages count as different — moves a guess into the part of the system that has the least information.

Frequently asked questions