A reliable integration needs more than a successful demonstration. Requests can time out, events can arrive twice, and a queue can accumulate work faster than it is processed. Design for those conditions, so a temporary failure does not create duplicate bookings, lost enquiries or conflicting records.
This guide explains webhooks, queues, retries and idempotency through the decisions a business needs to make. Delivery guarantees vary between services, so confirm the contract for the actual implementation.
Distinguish requests from event notifications
An HTTP request receives a response, but that response may only acknowledge acceptance. A webhook notifies another application that an event occurred. Establish which message is authoritative for the business state and what the receiving system must do with it.
Do not treat a customer returning to a confirmation page as the only evidence that payment or fulfilment succeeded. The browser can close or lose its connection. Use the agreed authoritative processing route and make the visible confirmation consistent with it.
Verify incoming events
Use the provider's supported authentication or signature-verification method and preserve the request information it requires. Check the destination and environment, so test events cannot alter production records. Keep secrets out of public pages, shared logs and client-side code.
Record a safe event identifier and processing outcome. Validation of the sender establishes one part of trust; the application must still check the event's meaning, permissions and relationship to an existing business record. An authenticated message can be irrelevant or already processed.
Make duplicate handling explicit
Idempotency means that repeating the same intended operation does not create additional effects beyond the agreed result. An idempotency key needs a defined scope, retention period and relationship to the request's parameters. Reusing a key for a genuinely different action can produce the wrong outcome.
Record the operation and its result through an atomic strategy suited to the application's storage model. A separate check followed by an unprotected insert can allow concurrent requests to create duplicates. Establish how delayed retries, changed parameters and incomplete operations are handled.
Retry failures selectively
Retry temporary failures according to the service's contract, using bounded attempts and suitable backoff. Rate-limit responses may include timing information, but the headers and interpretation vary. An invalid address or rejected permission usually needs correction, rather than repeated identical requests.
A timeout can leave the caller uncertain whether the action happened. Check the operation's known state or use an appropriate idempotent retry before creating a second action. Define the point at which uncertainty is assigned to staff for reconciliation.
Use queues with known delivery behaviour
A queue can separate event receipt from processing and absorb temporary bursts. Some queues can deliver a message more than once or out of order. Others offer different guarantees under defined conditions. Read the actual configuration and design the consumer around those guarantees.
Measure arrival rate, processing rate, oldest-message age and failures. When work arrives faster than it can be completed for a sustained period, the backlog grows. A queue changes when work happens; it does not create unlimited processing capacity or remove the need for operational ownership.
Plan ordering and reconciliation
If a customer changes a booking twice, an older event arriving late should not silently overwrite the newer state. Use the application's supported version, timestamp or authoritative-state strategy and test competing updates. State which system decides the current result.
Some rescheduling workflows cancel one booking and create another. Preserve the relationship between the old and new records, so the cancellation is not mistaken for an abandoned customer. Report the actual business outcome, not just the number of isolated event types received.
Handle exhausted retries and compensation
A dead-letter queue stores messages that require further investigation after processing fails. It is not automatically a usable staff task list. Build the information, access and procedures needed to inspect a failure safely, correct the cause and decide whether replay is appropriate.
Where a workflow needs compensation, define the business action that reverses or balances a completed step. Compensation can fail and may need to account for later changes. Blindly restoring an old record can erase valid work performed after the original operation.
Test the failure paths before launch
- Deliver the same event twice and confirm the intended single effect.
- Simulate delayed and out-of-order events.
- Interrupt a request after processing starts.
- Exercise rate limits, retry exhaustion and recovery.
- Verify the exception owner and safe replay procedure.
- Check that monitoring identifies stalled work.
Keep a record of the guarantees tested and remaining limits. Our software requirements guide helps turn these behaviours into acceptance criteria. Giraffe Digital's digital strategy service can connect the integration design with the staff processes needed to operate it.
