Enterprise Software / Buyer’s guide
The Webhook Arrived Twice. The Work Should Not.
Commission a webhook integration that handles duplicates, late events and missing deliveries. A practical scope and acceptance guide for business software buyers.
The short answer
Scope the business outcome, not just the endpoint. Agree how the integration authenticates a notification, records it durably, recognises repeated deliveries and tracks unfinished work. Define late-event handling, recovery and reconciliation with the source system. Accept the connection using controlled duplicate, interrupted and missing-delivery scenarios—not a single successful notification.
Discuss your project ↗
Our take
“We received it” and “the work is done” are different promises. Your integration should make the distance between them visible.
In this article
01 / 07
One request. Two notifications. How many jobs?
A customer submits service request B-204. Its portal sends a webhook—a notification to another system—so the operations team can prepare the work. The receiving system saves the job, but the acknowledgement never reaches the sender. A second delivery follows. Should a second job appear?
This is an illustrative situation, not a client incident. The answer is clear to a person at a receiving counter: check what the delivery refers to before preparing another folder. Software needs that distinction designed into the workflow.
When buying a connected portal or business system, “webhook integration included” leaves too much unsaid. Ask what the notification is supposed to cause, how the team will know that happened, and what remains visible when it did not.
02 / 07
Separate the event, the delivery and the effect
An event describes something that happened in the source. A delivery is an attempt to tell your system about it. A business effect is the work your system performs in response. One event can have several delivery attempts; one delivery can trigger several separately tracked effects.
In our example, event E-72 says request B-204 was submitted. Two deliveries of E-72 should still lead to one intended work item. A later cancellation is a different event, not another copy to discard merely because it mentions B-204.
Stripe documents duplicate events, delivery without an ordering guarantee and asynchronous processing. It recommends returning a successful response promptly rather than waiting for complex downstream work. These are useful reasons to separate a transport acknowledgement from completion—not a universal implementation contract for every provider.

Record the provider’s actual event identifiers, retry policy, acknowledgement deadline and replay facilities in the scope. GitHub’s documentation, for example, says a redelivered webhook retains its X-GitHub-Delivery value. Do not assume another provider uses the same header or identity rules.
03 / 07
Are you updating a picture—or preserving a story?
A status panel might only need the current state of B-204. An approval history may need every meaningful transition. Those are different integration products, even if both begin with the same notification.
For a current-state view, a webhook can prompt an authorised read from the source, followed by an update to the local view. That can help avoid applying an old snapshot over a newer one. It also adds API calls, access requirements, rate-limit handling and another failure point. It is not automatically the right answer for every event.
A transition-driven workflow needs more care. If “submitted” and “cancelled” arrive out of sequence, the integration must not reopen a cancelled job. Agree the authority for order—such as a documented source revision—and what happens when it is absent or ambiguous. Do not invent an ordering guarantee from arrival time. Stripe specifically cautions against using an event’s creation timestamp to establish order or deduplicate events.
Our recommendation: write the late-event rule in business language before choosing the mechanism. For B-204, “an older notification must not reactivate a cancelled request” is reviewable. “We sort the messages” is not a complete answer. If the workflow must preserve historical transitions, fetching today’s state cannot by itself recover yesterday’s missing history.
04 / 07
A receipt should open tracked work, not hide it
A queue is useful when work must outlive the incoming request or absorb bursts. It also brings a worker, retry policy, monitoring and recovery responsibility. A small, bounded action may be completed within the provider’s request deadline; the proposal still needs to explain interruption and repeat handling. Neither architecture makes an unreliable business operation safe by its name alone.
For background processing, our proposed contract is simple: acknowledge acceptance only after the notification has passed the required checks and the agreed work has been recorded durably. Then track received, pending, completed and failed or review-needed outcomes. An inbox entry is not a completion record.
Ask the supplier to show two copies arriving together and a worker stopping midway. Recognising a previously completed event is not enough: a “seen” flag written before the action can cause a retry to skip unfinished work. Concurrent deliveries need a safe way to claim the same work; interrupted work needs an owned recovery path.
Use identities scoped to the relevant source, account and tenant. Keep delivery attempts linked to the event, and track each consequential effect separately. If an external system may have accepted an action before a timeout, investigate its status or reuse its supported operation identity; do not blindly issue the action again. Where the dependency cannot provide that certainty, make the ambiguity visible and agree a manual decision route. Do not accept an unexplained “exactly once” promise spanning independent systems.
05 / 07
Ask for the awkward demonstration
A green endpoint and one successful notification show a narrow happy path. The following is Axiom Forge’s proposed acceptance record for the invented B-204 workflow. Adapt the outcomes to the provider and architecture; use controlled environments and synthetic records, not experiments on real customer work.
| Scenario | Agreed outcome | Evidence to inspect |
|---|---|---|
| The same event arrives twice, including concurrently | Both attempts are accounted for; one intended work item is created. | Attempt records link to one event and the actual downstream item—not just two HTTP successes. |
| Processing stops after receipt | Accepted work stays visible and can resume without skipping an unfinished effect. | Durable state, recovery ownership and the final business record after controlled recovery. |
| An older event arrives after cancellation | The agreed authority and late-event rule apply; B-204 does not silently reopen. | Relevant source state or revision, the decision taken and the resulting local state. |
| A notification never arrives | The agreed reconciliation identifies the discrepancy and routes repair safely. | A known source record missing locally, its detection and a recorded repair or exception. |
| Authentication is invalid or the tenant is wrong | No unauthorised business effect occurs. | The rejected or quarantined attempt, with no leaked secrets or cross-tenant changes. |
| An unexpected event type or payload version arrives | The documented ignore, reject or review policy applies; incompatible data is not silently processed. | A visible reason, alert where required and no false completion record. |
Include the difficult interval after an external action but before local completion is recorded. The evidence should show how the team determines what already happened. Keep the build, synthetic event set, expected results and observed records together so sign-off can be repeated after a change.
06 / 07
Who notices the job that never entered the inbox?
An inbox can report its own failures. It cannot count a notification it never received. Shopify explicitly documents that webhook delivery is not always guaranteed and recommends reconciliation jobs to keep systems aligned. That is a useful procurement question even when your chosen provider is different.
Agree which source records can be checked, how often, what delay the business can tolerate, and who owns discrepancies. The comparison must reflect the workflow: current status may be enough for a view, while a historical process needs an appropriate event history or another agreed recovery source. If the source offers neither, record the limitation instead of promising perfect recovery.
Give operators a clear view of ageing pending work, repeated failures and unresolved outcomes—not only request volume. Name the person who can replay work and the approval needed for consequential effects. A replay button is another way to perform the operation; it needs an explicit permission boundary and an audit trail.
Also decide what diagnostics contain and how long they are retained. Useful investigation usually needs identifiers, timings, state and reasons; unrestricted copies of payloads can expose confidential data. Stripe’s signature guidance requires the original raw request body for verification, but that does not imply keeping every payload indefinitely in ordinary logs. Use the chosen provider’s verification procedure and plan secret rotation and subscription ownership at handover.
07 / 07
Buy one complete connection before adding ten more
Start with one source, one destination, named event types and a specific business effect. Compare proposals on receipt security, durable work, duplicate and late-event policy, exception handling, reconciliation and operating ownership. “Two systems connected” is not enough information to compare scope.
The trade-off is not simply custom code versus a connector platform. A managed connector may handle transport and retries while leaving business-level duplicate handling or missed-event repair to you. A custom service may fit unusual rules while adding a component your team must operate. Ask either supplier to demonstrate the same acceptance record and name the remaining manual work.
When access, source history or event semantics are unclear, resolve them in a bounded discovery stage. Do not price uncertainty as though every missing capability were already available.
Planning a webhook integration? Share the systems, event documentation, intended outcome and the exceptions that would matter to operations. Start a project brief or email hello@axiomforge.am. A redacted sample is useful; passwords, signing secrets and private customer payloads are not.
Sources and editorial scope
This is Axiom Forge’s procurement and product-delivery guidance, not a guaranteed project plan. The example is illustrative. Sources checked on 20 Oct 2026.
- Stripe — Receive Stripe events in your webhook endpoint — Provider-specific guidance on signatures and raw bodies, duplicates, ordering and acknowledgement. The procurement recommendations and B-204 example are our own.
- GitHub — Best practices for using webhooks — Event/action handling and redelivery identity. Its header contract is an example, not a standard promised by every source.
- Shopify — Webhooks overview — Delivery and ordering limitations and reconciliation guidance; not a guarantee that a source can reconstruct missing historical events.