Design repeated order notifications so they do not unintentionally create extra orders, deduct inventory again or send duplicate customer messages. Identify and durably store events, make business changes idempotent, and provide a recovery path. Start by distinguishing successful receipt from completed order processing.
[01]Why might a webhook arrive again?
A webhook delivers an external change through an HTTP request. Even after processing succeeds, a lost response can leave the sender uncertain. Stripe documents possible duplicate delivery and does not guarantee event order. Retry behavior, retention and response deadlines depend on the provider.
- Record what the event ID and delivery ID each identify.
- Check automatic retries, manual redelivery and delivery-history access.
- Distinguish multiple events for one order from out-of-order delivery.
[02]How do you separate receipt from completion?
GitHub asks receivers to return 2xx within 10 seconds and suggests queue-based asynchronous processing. That deadline is provider-specific. BOYD’s proposed flow is validate, durably persist, acknowledge, then process separately. If durable storage or enqueueing fails, choose the appropriate failure response under the provider’s contract.
Implement provider-specific signature verification. Stripe, for example, requires the unmodified request body for verification. Validate authenticity, supported event types and the destination account before admitting a request to business processing.
[03]Is a duplicate lookup enough?
Idempotency means repeating the same intended request without additional side effects. AWS emphasizes atomic handling of request identifiers and related state changes. A separate “look up history, then execute if absent” sequence can let concurrent workers both proceed.
For a relational database, consider NOT NULL and a unique constraint on account, provider and event identity. PostgreSQL UNIQUE constraints restrict duplicate column values or combinations. A claimed record still needs a processing state. Where business data and completion records share a database, consider committing them in one transaction.
Event deduplication and business deduplication differ. Distinct events may request the same business action. Define that action’s identity separately: blocking everything by order ID could discard valid cancellations or changes. Decide which operation should happen only once.
[04]Which failures should an order integration handle?
This hypothetical acceptance matrix assumes a payment notification updates an order and schedules fulfillment. These are BOYD’s suggested acceptance outcomes for a design review, not a customer case or provider guarantees.
| Test situation | Expected outcome |
|---|---|
| Deliver the same event concurrently | No duplicate active processing or business result |
| Stop the server before durable receipt | No false receipt success; redelivery can recover |
| Stop a worker after durable receipt | Incomplete work remains discoverable and recoverable |
| Lose the response after applying a business change | A retry recognizes the result without repeating the change |
| Deliver update and cancellation events out of order | State-transition or version rules prevent incorrect regression |
An example state model is pending, processing, completed and failed. Define recovery for stale processing records. When reclaiming a lease or lock, consider whether the previous worker could still perform an external action.
[05]Does local deduplication cover an external API call?
Updating a local order and calling a shipping or email API change separate systems. A local transaction does not automatically commit both. AWS’s transactional outbox pattern records business data and an outgoing message in one transaction, then uses a separate process to deliver the message.
Outbox delivery can repeat, so receivers still need idempotent processing. If the external API supports idempotency keys, reuse a key for the same intended action and define how to check results after a lost response. Otherwise, consider reconciliation or operator review before repeating a consequential call.
[06]How should failed work be recovered?
BOYD recommends defining what must be checked before retrying, alongside a retry limit. Separate transient network failures, invalid data, permission issues and uncertain outcomes, and assign a response and owner. For an uncertain external call, provide a way to determine completion before blindly repeating it.
- Correlate event and business identifiers with attempt time, state and failure reason.
- Require authorized operators to record the target and reason for reprocessing.
- Use incomplete-work counts and oldest pending age to agree on a review cadence.
- Retain necessary diagnostic identifiers rather than indiscriminately logging payloads or secrets.
[07]What should you agree before implementation?
- Have you checked each provider’s signatures, deadlines, redelivery and lookup tools?
- Have you distinguished event identity from the business operation performed once?
- Do acceptance scenarios inject concurrent duplicates and mid-process failures?
- Are transaction boundaries and external-send recovery defined?
- Are reprocessing access, incomplete-work alerts, handover and ownership assigned?
When requesting an integration proposal, include sample events, a business-state diagram, provider redelivery rules and these acceptance outcomes in the deliverables. Starting with one order flow makes implementation scope and operational ownership easier to discuss together.
- Webhooks
- API integration
- Idempotency
- Reliability
