A webhook sends an event to your integration. Consumers should verify authenticity, handle repetition and reconcile state under the documented contract.
01STORY BRIEFThe idea in three screens.3 SCREENS
A webhook reports an event. It does not replace your state.
A webhook sends an event to your integration.
Do not assume events arrive exactly once or in the expected order. Retain identifiers when provided and allow reading current state. Signing secrets belong in appropriate storage, not client code. Users then see progress grounded in verified events.
A consumer can retain the latest confirmed state and receipt time. If an event appears contradictory, reading source state can resolve it under the available contract. Keep an incident record without exposing the signing secret. Reliability is built in these recovery paths, not merely in receiving the first demonstration event. Test duplicate and delayed delivery cases before depending on the integration for unattended decisions.
Treat the notification as a delivery system
A webhook tells your system that an event was sent; it does not automatically guarantee that the event will arrive once, in order, or at a convenient time. Design the receiver around the provider's documented delivery contract. Verify authenticity using the supported mechanism, reject malformed payloads, and acknowledge only after the event has been safely accepted for processing. Keep the public endpoint narrow. It should not turn arbitrary event text into an instruction for an agent with publishing or spending permissions.
Receive, record, reconcile
- 01Verify
Authenticate the delivery through the provider contract.
- 02Persist
Keep the event identifier and processing state.
- 03Apply
Update the operation safely, including duplicates.
Editorial model: a way to reason about the process, not measured platform results.
Deduplicate with stable event identifiers where available and make handlers safe to repeat. If two events arrive out of order, use the underlying resource state or documented sequence information to reconcile them instead of letting the last network arrival blindly win. Record processing failures and provide a replay path with bounded retries. Avoid storing more payload data than the operation needs. A webhook integration earns its keep when an operator can answer which event arrived, what it changed and how to recover if that change did not complete.
“A webhook reports an event. It does not replace your state.”
02FIELD KITFrom concept to practice.2 SCREENS
Apply documented verification.
Adapt this to your audience, budget and test scope.
Put it to work.
- 01Apply documented verification.
- 02Plan deduplication and reconciliation.
Notes & sources.
The limit. A received event is trustworthy only after service-appropriate checks.
Further reading is linked throughout this article. Worked examples explain a process; they are not campaign results.
THE ORGANIC CLUB is an editorial project initiated by TokPortal. That relationship is separate from the evidence behind claims. Editorial signatures and image credits are explained in our policy. Our editorial policy →
.jpg){kind=link}