Webhook

An event post to an HTTPS endpoint: receipts, inbound messages and status changes that the receiver must verify, acknowledge fast and queue.

Definitions only — a term explained here is not a service we sell.

A webhook is an HTTPS callback that posts an event to a URL you registered, such as a delivery receipt or an inbound message. The receiver verifies the signature, acknowledges with 2xx and queues the work.

The receiver handles duplicates and out-of-order events; a webhook is push delivery.

Verify, acknowledge, queue

The provider sends a POST when an event happens, and your endpoint returns a 2xx to acknowledge it. The payload is usually JSON with an event type and an identifier. The provider may sign it; check the signature against the raw body with the shared secret and reject requests outside the replay window.

Verify first, store the raw event, return 2xx and process the work asynchronously. Slow endpoints cause retries. Delivery is usually at least once and order is not preserved, so deduplicate on the event ID. Keep a dead-letter queue for events that cannot be processed. The SMPP versus HTTP explainer compares callbacks with session-based delivery.

FAQ

What is the difference between a webhook and an API?

An API is usually pulled by the client. A webhook is pushed by the provider when an event happens, and most platforms offer both.

Why do events arrive twice?

Delivery is usually at least once, so a retry can duplicate an event already processed. Deduplicate on the event ID.

What status should I return?

A 2xx once the event is persisted or queued. Returning 2xx earlier risks losing the event when the next step fails.

Learn more

Sources

  1. IETF RFC 9110: HTTP Semantics