Webhook

Overview

A webhook is an asynchronous HTTP message sent by one system to notify another system that a defined event occurred. A Webhook is a producer-initiated HTTP event delivery pattern; it differs from client polling and does not guarantee downstream processing after receipt. Webhook delivery is usually at least once, not exactly once. Messages can be duplicated, delayed, reordered, forged, or lost after retry exhaustion. Replay of Webhook should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.

Receivers should use HTTPS, verify signatures, validate schemas and business fields, persist before acknowledging, and deduplicate atomically. The client should store the provider reference, await or query authoritative status, handle duplicate events idempotently, and reconcile the final object before triggering irreversible downstream work. Documentation for Webhook should include prerequisites, authentication, environment and base URL, schemas, examples, state transitions, errors, idempotency, limits, webhook behavior, security guidance, changelog, and recovery procedures. Monitoring for Webhook should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events.

Metrics should separate transport success from business success. A valid delivery also does not prove that downstream processing or the underlying business outcome completed. Instead of repeatedly polling for changes, the provider sends an event to a registered endpoint when a payment, order, account, or other resource changes. Silent coercion or guessed defaults can create valid-looking but financially incorrect records. Replay tools, monitoring, authoritative status queries, and periodic reconciliation cover gaps and recovery.

The receiver acknowledges delivery and processes the event. Least-privilege scopes, environment separation, rotation, revocation, and protected logs reduce the impact of credential exposure.