Webhook delivery handling
Measure webhook receipt and completion separately
A provider can see successful delivery while the application backlog grows. Track durable acceptance, processing age and final effects as different stages.
In this article
Define the receipt promise
Record verified requests accepted durably, invalid requests rejected and storage failures that prevented acceptance. Keep provider and account dimensions bounded and appropriate to the monitoring system.
A successful acknowledgement should correspond to an accepted record or the documented handling of an already accepted duplicate.
Do not count unsupported event types as completed business work merely because the endpoint returned success under its subscription policy.
Follow processing from receipt
Measure time from durable receipt to the required outcome. Include pending events that have not completed rather than calculating latency only from successful workers.
Track the oldest eligible event and failed or held work. An average can remain low while one event retries for days.
Separate duplicate receipt count from duplicate business effects. Frequent delivery retries may be harmless if effects remain protected, but they can still indicate an acknowledgement or network problem.
Check the effect's correctness
Use reconciliation appropriate to the business action. A processed flag should correspond to the expected local state or confirmed external result.
For an illustrative set of 1,000 accepted events, 990 completed, eight pending and two uncertain should remain visible. Reporting a 100 percent delivery success rate describes only the provider-to-inbox stage.
Preserve operation identities for controlled investigation without putting full payloads into general dashboards.
Include recovery evidence
Test receiver storage failure, worker outage and duplicate delivery. Confirm that alerts and runbooks identify the stage that needs attention.
Measure recovery progress after the worker resumes, including new events arriving during catch-up. A growing backlog can mean processing capacity remains below incoming demand.
Accept the integration when acknowledged work is recoverable and processing outcomes are traceable. Fast endpoint responses are valuable, but they are only one part of a dependable webhook workflow.
Primary sources
GitHub: webhook best practicesReferences checked 11 September 2026.