Webhook delivery handling
The provider says delivered but the application did nothing
Trace the event from acknowledgement to durable receipt and worker outcome. The missing stage determines whether to replay, repair or reconcile.
In this article
Find the provider delivery identity
Use the provider's controlled delivery history and the expected account context. Record the event or delivery identity, response status and timing.
Confirm that the request reached the intended environment and endpoint. A stale test URL or old deployment can acknowledge events without updating the current application.
Keep sensitive payload inspection within the authorised tools.
Look for durable receipt
Search the inbox or equivalent accepted-work store. If no record exists despite a success response, investigate whether the receiver acknowledged before persistence or used an unreliable background task.
Do not immediately request redelivery if the event may already have produced an external effect. Check the processing and operation records first.
If receipt exists, inspect its state, claim and retry timing. A worker lease or unsupported version may be preventing progress.
Inspect the business outcome
Compare the processed marker with actual application state. If an external request was attempted, establish its outcome through the supported provider lookup or reconciliation path.
A lost worker response can leave the effect complete while the local record remains uncertain. Blind replay can repeat it.
For a safe local projection, a controlled retry may be sufficient once the underlying defect is fixed. Choose the action according to the effect, not a generic replay button.
Repair the stage that failed
Fix receipt durability, worker discovery or processing logic as indicated by evidence. Test the observed failure boundary with a synthetic event.
Use provider redelivery only under its documented behaviour and the application's duplicate protection. Preserve the original event identity where the provider does so.
Verify the normal business result and record affected events from the same failure window. The incident is closed when missing work is accounted for and future acknowledgements reliably correspond to recoverable processing.
Primary sources
GitHub: webhook best practicesReferences checked 11 September 2026.