A webhook retry should not become another service job. The integration needs to recognize that several deliveries can describe one business event, and that an uncertain create response may conceal a successful remote write.
Use two layers of identity. The event identifier distinguishes repeated deliveries. The business action key distinguishes multiple events that all request the same job, such as call completion and a later contact update.
Persist before acknowledging work
Store the incoming event and its account identity before processing it. Validate that it belongs to an authorized source and client. Then create or find a local action record for the intended job. The action record should survive process restarts and concurrent workers.
A local uniqueness rule can ensure only one worker owns that action key. It cannot by itself prove that the external system created the job exactly once. The remote API's supported idempotency or lookup mechanisms determine how safely you can recover uncertain results.
Follow an illustrative timeout
A caller requests a furnace visit. The integration submits a create request, but the network connection ends before the response arrives. The webhook is delivered again.
A naive handler repeats creation and produces a duplicate. A safer handler finds the existing action marked uncertain, attempts to reconcile through a supported identifier or staff review, and records the discovered remote job. Only a verified absence under the chosen recovery policy permits a new creation attempt.
| Failure point | Expected recovery |
|---|---|
| Before local event save | Source may retry; no action claimed |
| After save, before processing | Worker resumes durable pending item |
| During remote creation | Outcome becomes uncertain |
| After remote ID saved | Retry returns existing action result |
| Two workers receive event | One action claim succeeds |
Give uncertain work an operational owner
An “uncertain” state must lead somewhere. Provide a queue with account, request details, attempted time, and reconciliation evidence. Staff should know whether they are checking for an existing job or authorized to create a new one.
Keeping all requests in one global deduplication key is unsafe across clients. Scope keys by account and business purpose. Also distinguish a legitimate second job from a repeated delivery: the same caller may need service at two properties.
The tradeoff is additional storage and operational review. At low volume, manual reconciliation may be acceptable. At higher volume, supported remote idempotency and precise action tracking become more valuable. Do not claim “exactly once” merely because duplicate webhook identifiers are filtered.
Review debugging voice agent failures for the evidence needed to trace a call into its resulting actions.
Questions about webhook retries
Can the call identifier be the only key?
Only if the business guarantees one relevant action per call. Multi-property or multi-service calls usually require more specific action identities.
Should retries stop after one failure?
Transient failures may be retryable, but use bounded attempts and a visible terminal or review state. Unknown outcomes require reconciliation.
How long should deduplication records remain?
Choose a retention window that covers source retries and operational recovery, then document it. Removing records too early can make an old delivery appear new.