A successful webhook response confirms the receiver’s stated delivery boundary, not necessarily the final customer action. Track delivery, durable acceptance, processing, and business completion as separate states.
Delivery and execution have different contracts
Webhook delivery moves an event from a sender to a receiver. Business execution changes a record, sends a message, or performs another domain action. A receiver may acknowledge delivery before a queued worker performs that action.
For a proposed contract, define exactly what an acknowledgement means. The receiver should establish the chosen durable boundary before acknowledging accepted work. The worker then records processing attempts and authoritative results independently.
Do not label an HTTP success response “customer updated” in a dashboard unless the endpoint’s documented contract establishes that result. A fast acknowledgement can improve delivery reliability while leaving execution pending or failed.
Follow a fictional customer-update event
A provider sends an address-change event. The receiver verifies it, saves a receipt, and acknowledges the delivery. A queued worker later discovers that the customer reference cannot be mapped. Delivery succeeded; the customer update did not.
Staff need the unresolved mapping task, not a green delivery badge interpreted as completed work. Once the mapping is resolved, the operation can resume under its duplicate-protection rules without requiring the provider to invent a new event.
| Observed state | Permitted interpretation |
|---|---|
| Request reached endpoint | Delivery was attempted |
| Durable receipt accepted | Work is retained for processing |
| Worker started | Execution is in progress |
| Authoritative record updated | Defined business action completed |
| External response lost | Outcome remains uncertain until reconciled |
A replayable fixture should pause the worker after acknowledgement and inspect both dashboards. The provider delivery view should show its proper success, while the application accurately shows pending business work.
Report separate latency measures
Measure delivery latency, queue wait, processing time, and end-to-end completion. Combining them into one response-time metric hides where callers or staff wait. A short endpoint response can coexist with an old processing backlog.
This separation adds state and monitoring work, but it prevents false completion claims and unsafe retries. Keep the state model concise enough that operations can distinguish pending, failed, uncertain, and completed without reading implementation logs.
The workflow here is proposed. The voice integration case study describes relevant backend work without claiming this exact receipt architecture. Pair it with webhook receipt auditing.
Delivery versus action FAQ
Does a successful delivery mean the customer record changed?
Only if the documented endpoint contract guarantees that business result. Queued processing usually needs separate evidence.
Should failed business work force provider redelivery?
Not necessarily. A durable accepted event can be retried internally according to its operation policy.
What should staff see?
Show the actual business state and next owner, with delivery details available for diagnosis rather than substituted for completion.