Key takeaways
- A webhook notifies a receiver that an event occurred; it is not an exactly-once delivery guarantee.
- Verify authenticity and durably accept work before acknowledging it.
- Handle duplicates, ordering and reconciliation explicitly.
Overview
Webhook delivery is an integration boundary, not a guarantee of exactly-once processing. Providers may retry, send events out of order or time out after your system has already accepted work. Verify the event’s authenticity, record a stable event identifier and process consequential changes idempotently. Use the provider’s current documentation for signature and retry behavior.
How it works
Register an endpoint for the events the integration actually needs.
Verify incoming requests and persist the event before acknowledging it.
Process safely, deduplicate repeats and reconcile missed or out-of-order events.
Design the receiver as an event boundary
A receiver should know which provider sent the event, which account it belongs to and which event types it accepts. Use the provider’s documented signature or authentication process before applying changes. A hard-to-guess endpoint URL is not a substitute for verifying the request, and a payload’s claimed workspace should not override authenticated connection scope.
Keep the acknowledgment path short enough for the provider’s timeout, but make it durable. If the endpoint returns success before saving the event, a process crash can lose work that the provider believes was accepted. Longer processing can happen from a durable queue with its own retry and failure visibility.
| Stage | Responsibility | Evidence to retain |
|---|---|---|
| Authenticate | Validate the provider’s request | Verification outcome without exposing the secret |
| Accept | Persist the event or durable job | Stable provider event ID and account scope |
| Process | Apply the intended idempotent change | Operation result and affected resource |
| Reconcile | Recover missed or uncertain work | Current authoritative state and recovery status |
Source material: GitHub — Best practices for using webhooks ↓
Expect repeated and out-of-order events
A provider may retry after a timeout even if the receiver completed the action. Deduplicate using the provider’s stable event identity and make consequential operations idempotent. Do not generate a new business operation for each delivery attempt. Delivery identity and business-event identity may be different, so read the contract carefully.
Arrival order may also differ from event order. A delayed update should not overwrite a newer resource state merely because it arrived last. Use documented versions, timestamps or a fetch of authoritative current state where appropriate. Preserve enough context to explain why an older event was ignored rather than marking it as an unexplained failure.
Test the failure paths before relying on notifications
An illustrative list-completed event arrives twice. The receiver should produce one destination update and record that the second delivery was already handled. Then test a crash after persistence, an unavailable destination and a malformed signature. These cases reveal whether acknowledgment, processing and recovery are actually connected.
Monitor failed events and provide a replay or reconciliation path that respects the original operation identity. Providers have different retry windows and retention, so do not assume an event will be retried forever. Periodic reconciliation may be necessary for important state even when normal webhook delivery is reliable.
What this looks like in practice
A list-completed event arrives twice after a network timeout. The receiving integration recognizes the same event identifier and sends one CRM update rather than duplicating the list.
Examples explain the concept; they are not reported customer results.What to check
Test bad signatures, duplicates, delayed delivery and unavailable dependencies. Ensure an acknowledgment means the event was durably accepted, not merely received in memory.
Common mistake
Returning success before saving the event, then losing work on a crash, or assuming the order of arrival is the order of business events.
Webhook vs. REST API
Polling a REST API asks whether anything changed. A webhook pushes a notification when an event occurs. The receiver may then call an API to retrieve authoritative current state.
Read the REST API definition →Questions answered
What is a Webhook?
A webhook is an HTTP notification sent by one system to a configured endpoint when an event occurs, allowing another system to react without continuously polling for changes.
Should webhook processing happen synchronously?
Keep acknowledgment within the provider’s timeout. Durable queuing is often appropriate for longer work, with retries and failure visibility handled separately.
Can a webhook be trusted because its URL is secret?
A hard-to-guess URL is not a substitute for the provider’s documented authentication or signature verification. Validate the request before applying changes.
Should a webhook trust every field in a validly signed payload?
A valid signature establishes the provider’s request authenticity under its scheme, not that every field is suitable for every action. Validate the event type, schema, account scope and business rules. User-controlled text inside the payload remains data and should not become instructions for an AI agent.
Can a webhook be replayed safely?
It should be designed for replay, but safety depends on stable event identity, idempotent effects and current authorization. Replaying a raw request through a receiver without those controls can duplicate writes or messages. Retain the event outcome and distinguish deliberate recovery from a new business event.
References and further reading
Primary documentation and source material for this topic. Sources checked September 14, 2026; provider requirements can change.
- About webhooks ↗GitHub
- Idempotent requests ↗Stripe
- Best practices for using webhooks ↗GitHub
Continue reading on the blog
Explore all articles and guides →Put the concept to work.
Explore the relevant AstroFabric workflow and see how the pieces connect.
Help keep this guide useful. Suggest a correction or browse the full glossary.