Reliable Website Webhooks: Handle Retries Without Duplicate Actions

Model delivery separately from the business action

A webhook tells an application that something happened in another system. It is not a promise that one request will arrive exactly once in the order the business expects. Providers can retry, and different events can describe related changes. Start by naming the event and the action it should trigger, such as updating a payment record or refreshing published content. Keep delivery receipt separate from completing that action. This distinction lets the system recover without creating a second order, sending repeated emails or publishing conflicting states.

Write the receiver contract from the selected provider’s documentation. Identify event identifiers, supported event types, signature verification rules and retry behaviour. Stripe, for example, documents duplicate deliveries and warns against depending on event order. Those rules are provider-specific evidence, not a universal description of every service. Record the actual integration version and environment. A test endpoint and a production endpoint may use different signing secrets, so configuration needs a deliberate owner.

Authenticate the event before trusting its contents

Use the provider’s supported verification method and its official libraries where appropriate. Signature validation often depends on the original request bytes; framework middleware that transforms the body can break the check. Keep signing secrets in a controlled server arrangement and do not expose them to browser code. After verification, validate the expected event type and relevant object context. A legitimate signature does not mean every event belongs to the action your endpoint implements. Apply the business’s access and state rules as well.

Limit receiver work to a safe observable path. An endpoint can verify and durably record or queue an accepted event, then acknowledge according to the provider contract. Do not acknowledge success before the event is safely retained if losing it would matter. Equally, avoid performing a slow chain of external actions in the request when a suitable worker arrangement can handle them more predictably. Define failed, pending and completed states so staff can distinguish an accepted delivery from a completed business operation.

Design duplicates and business transitions deliberately

Use a durable deduplication record for the relevant event identity, with a concurrency-safe way to prevent two receivers acting simultaneously. A memory-only list disappears on restart and is insufficient for an important operation. Review whether different event objects can represent the same logical transition, and use an appropriate business-level safeguard as needed. Do not treat a timestamp alone as a reliable identifier. Completion records and side effects should be coordinated so a crash cannot leave the action repeated while its deduplication marker remains missing.

Worked example: a retry sends two confirmation emails

Imagine an endpoint receives a successful payment event, sends an email and then times out before returning. The provider retries. If the receiver sends again without checking durable processing state, the customer gets a second message. Record and process the event through a deliberate duplicate-safe workflow, and give the email action its own relevant identity where needed. Review crash points around both the action and completion record. This hypothetical example demonstrates why repeating an identical request should not accidentally repeat a business effect.

Test delivery failures without guessing current state

Use provider-supported test tooling or controlled fixtures in a non-production environment. Replay the same accepted event, test a verification failure, simulate a worker interruption and deliver related events in a different order. Check whether the application consults current authoritative object state where its workflow requires it, rather than assuming that arrival order proves which state is newest. Tests should use synthetic records and avoid triggering real customer communications.

Add a bounded retry and investigation process for failed work. Staff need an event reference, status and understandable error context without unnecessary sensitive payload logging. Keep a dead-letter or review path where appropriate, and replay only through the same safeguards used normally. Monitor queue delay and repeated failures instead of showing only total received events. A reliable webhook integration is demonstrably recoverable and duplicate-aware; it does not claim that a provider or queue guarantees every downstream action can happen exactly once without application design.

Give a replay operation an explicit operator context and event reference. Staff should know whether they are retrying failed processing or deliberately repeating an already completed action. The latter may require a different business decision. Keeping those meanings separate reduces the chance that an investigation tool becomes an accidental duplicate-action button.

Practical checklist

• Verify signatures using the provider contract.
• Retain accepted events durably.
• Coordinate duplicate records and side effects.
• Test replay, interruption and reordered events.

Frequently asked questions

Related Articles