Webhook Integration Acceptance: Duplicates, Ordering and Recovery

This is a CodeMyTown implementation worksheet for a product owner and developer. We sell source code and frontend templates. The sample events below are invented planning fixtures, not a provider API or functionality supplied by a template. Use your own authorized staging environment and sandbox accounts.

Start with the business effect, then identify the event

Choose one small workflow, such as updating the delivery status of a synthetic order. Define the source system, the event that represents a change, the record it may affect and the observable result. Name the system of record. A receiving endpoint can acknowledge a request while a later worker still has no valid order to update.

Write down the event identity separately from the business identity. An event reference identifies a delivery subject; an order reference identifies the business record. Repeated delivery of one event and two distinct events concerning one order require different reasoning. Do not treat every later message about the same order as a duplicate, or assume that an event timestamp is a reliable sequence number.

Use a fixture that cannot affect real customers

The following neutral example is deliberately not a Stripe payload. Adapt the real provider's documented shape and verification procedure rather than sending it unchanged to a live integration.

{
  "event_ref": "sample-event-17",
  "kind": "sample.delivery_status_changed",
  "record_ref": "sample-order-8",
  "status": "ready_for_collection"
}

Before testing, create the sample order under the intended staging account. Disable real notifications, fulfilment and charging. Record the application's expected starting state and the test release. A unique marker helps connect the request, queue record and stored result without placing a customer's name or bearer token in your test notes.

Write the acceptance matrix before the first delivery

Run an allowed case before relying on rejection tests. If every request fails because the endpoint is misconfigured, no useful security or reliability boundary has been established. Record what is untested as well as what passed.

Verify the provider's contract instead of inventing one

Provider rules differ. For example, Stripe's webhook documentation describes duplicate deliveries, warns that generated events are not guaranteed to arrive in order, and requires the unchanged raw request body for its signature check. Those details are reasons to read the actual integration contract. They are not instructions to apply Stripe's signing format or event model to every webhook service.

Ask the developer to demonstrate verification with the maintained provider library and appropriate test credentials. A readable JSON document or an expected event name does not establish who sent it. Keep signing secrets on the server, transfer them through the agreed protected channel, and keep them out of browser code, screenshots and acceptance reports.

Separate receiving, processing and completion

Agree what a successful HTTP acknowledgement means in your architecture. If work continues asynchronously, decide when the event becomes durable, where pending work can be found and how processing failures become visible. A fast success response followed by a lost queue item is a different result from a fully completed business action.

Rehearse a controlled worker failure after acceptance. The receiving operator should be able to locate the synthetic event, explain its current state and follow the documented recovery step. Do not simulate an incident by interrupting a production queue. Also test a lost response: the sender may repeat an event even when your application already accepted it.

Define deduplication at the appropriate boundaries. A recorded event identifier can help detect a repeated delivery; a separate business-operation rule may still be needed to avoid duplicate fulfilment across related events. Agree the retention and concurrency behavior with the implementation team. A checkbox labelled “idempotent” cannot describe those choices.

Leave a usable handover record

Keep the event types enabled, the staging endpoint, relevant release versions, the verification method, accepted payload version, duplicate rule and recovery owner. Reference protected configuration locations without copying their secret values. Include one passing fixture, one rejected fixture and one recovered failure so another operator can repeat the checks.

Use our frontend/API contract worksheet to connect backend results to the interface, and our handover drill for the operating procedure. This checklist defines separately scoped backend integration work. In particular, StockNova is a sixteen-page HTML/CSS/JavaScript frontend template; it supplies no production webhook receiver, database or payment backend.