What Is a Webhook? Events, Delivery, Security, and Design

Scrapeless Scraping API can send an HTTP POST request to a configured webhook URL when an asynchronous scraping task completes.

What Is a Webhook?

A webhook is a mechanism through which one system sends an HTTP request to another system after an event. The receiving application registers an endpoint URL and often chooses event types such as task completed, invoice paid, record updated, deployment finished, or message delivered. When the event occurs, the producer calls that endpoint with event data and metadata.

A webhook is sometimes described as a reverse API call. In an ordinary API interaction, the consumer initiates a request to read or change state. With a webhook, the producer initiates a request to notify the consumer. The receiving URL is still an HTTP endpoint, and the implementation must apply ordinary API security, validation, availability, and observability practices.

The Standard Webhooks specification collects conventions for secure and interoperable webhook delivery. It covers payloads, event metadata, signatures, and operational behavior, while individual providers still define their own event types and contracts.

How a Webhook Works

1. The consumer registers an endpoint. Registration may occur in a dashboard or API and usually associates a secret with the subscription.
2. The consumer selects events. Narrow subscriptions reduce unnecessary traffic and data exposure.
3. The producer records an event. A domain action creates an immutable event or delivery task with a stable identifier.
4. The producer builds the payload. It serializes an event type, event ID, occurrence time, schema version, and relevant data.
5. The producer signs the delivery. The signature covers the raw body and freshness metadata under the documented scheme.
6. The producer sends an HTTP request. POST with a JSON body is common, but the contract determines method and media type.
7. The consumer verifies and records it. The endpoint checks transport, signature, timestamp, event ID, schema, and subscription before accepting the event.
8. The consumer acknowledges. It returns the documented success status after durable acceptance and performs longer processing through a queue or worker.

Webhook Payload Example

A small event envelope can separate metadata from domain data:

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

The date shown is an illustrative code constant rather than a publication stamp. The event ID supports deduplication, the type selects the handler and schema, the occurrence time describes the domain event, and the version controls payload evolution. Delivery time belongs in request metadata when the signature scheme uses it.

Do not assume a webhook body contains the full current resource. Some producers send a thin notification with an ID, after which the consumer calls the API to fetch authorized current state. Others send a complete event snapshot. The contract should state whether the payload represents the event, the resource after the event, or a pointer.

Webhooks vs Polling, APIs, and WebSockets

Important systems often combine patterns. A webhook provides fast notification, while a scheduled reconciliation process compares current API state with local state. The webhook improves latency; reconciliation detects gaps or policy changes without assuming that one delivery path is perfect.

How Webhook Signatures Work

A shared-secret design commonly uses a keyed hash over the exact raw request body plus metadata such as a delivery timestamp and event ID. HMAC is a standard construction for message authentication, defined in RFC 2104. Other providers use asymmetric signatures so consumers can verify with a public key.

The consumer must follow the provider’s byte-for-byte algorithm. Parse the signature header according to its versioned format, reconstruct the signed content exactly, calculate the expected value, and compare through a constant-time function. Only after verification should the code parse and trust the JSON payload.

Framework middleware can break verification when it parses JSON and serializes it again. Whitespace, property order, escaping, and number formatting may change even though the data appears equivalent. Capture the raw body bytes before ordinary body parsing, then pass the verified bytes to the JSON parser.

Replay Protection and Idempotency

A valid old webhook can be maliciously replayed if the signature never expires. Signature schemes therefore include a delivery timestamp or another freshness value. The receiver accepts only a small documented time window and should keep its clock synchronized. The timestamp check supplements, rather than replaces, event-ID deduplication.

Idempotency means processing the same logical event more than once produces the same business result as processing it once. Store the producer’s stable event ID in a table with a uniqueness constraint, ideally in the same transaction that applies the business change. Marking an event “seen” before the business update can lose work if the process stops between those actions.

Some operations are naturally idempotent, such as setting a record’s status to a specific version. Others, such as incrementing a balance or sending a message, need an idempotency record tied to the event ID. Deduplicate by the producer’s documented identifier, not by hashing the payload, because two legitimate events may have identical bodies.

Ordering and Event Versions

Delivery order may differ from occurrence order because events can travel through separate workers, regions, or queues. A newer update may arrive before an older one. Consumers should not treat arrival order as business order unless the producer explicitly guarantees it for the subscription.

Include a resource version, sequence, or event occurrence time with defined semantics. Apply a state update only when its version is newer than the local version. For events that represent immutable actions rather than state snapshots, preserve the event sequence rules established by the domain.

Schema version is separate from resource version. Schema version describes payload shape; resource version describes the state of a particular entity. Keeping the concepts distinct prevents a payload-format change from appearing to be a newer business record.

Acknowledge First, Process Through a Queue

A webhook endpoint should do bounded work: enforce request size, verify the signature, validate the envelope, reserve the event ID, store or enqueue the accepted event, and return the documented success response. Slow database joins, external API calls, file generation, and email sending belong in workers.

Durable acceptance is important. Returning success before the event is recorded can lose it if the process stops. Waiting for every downstream action before responding makes the producer hold a connection and may cause repeated deliveries when the endpoint exceeds its response deadline.

The queue message should contain the verified event, subscription context, and safe tracing identifiers. Secrets used for signature verification do not belong in the queue payload.

Endpoint Registration Security

If users can register arbitrary webhook URLs, the producer becomes an HTTP client acting on user input. The system must protect against server-side request forgery. The OWASP SSRF Prevention Cheat Sheet describes allowlist and network-layer controls.

Require HTTPS for public endpoints, resolve and validate destinations, block loopback, link-local, private, metadata, and internal service ranges, and apply the checks again after redirects and DNS resolution according to the chosen policy. Limit ports, methods, response bytes, connection time, and redirect behavior.

Verify endpoint ownership during registration through a challenge or signed handshake. Treat webhook response bodies as untrusted and do not expose internal network details through delivery error messages.

Common Webhook Use Cases

Observability and Operations

Track event ID, subscription ID, event type, schema version, received time, verification decision, acknowledgement status, processing state, and safe correlation identifiers. Do not log signing secrets, full authorization headers, or sensitive payload fields.

Measure acceptance latency, queue delay, processing duration, duplicate rate, signature failures, invalid schemas, stale timestamps, and ordering conflicts. Separate producer delivery health from consumer business-processing health so an accepted event that fails later does not disappear into a generic success metric.

Provide a controlled administrative view that can search by event ID and show redacted delivery history. Operations teams need enough evidence to diagnose a missing state change without exposing the credential or full sensitive body.

Webhook Design Checklist

1. Define stable event types and IDs. Document whether payloads are events, snapshots, or pointers.
2. Version the schema. State compatibility rules for new optional fields and event revisions.
3. Sign raw bytes and freshness metadata. Publish exact verification steps and support secret replacement.
4. Enforce endpoint security. Verify ownership and block SSRF destinations.
5. Accept idempotently. Use a unique event ID and a transactionally safe deduplication record.
6. Acknowledge after durable acceptance. Move longer work to a queue.
7. Expect repetition and reordering. Use resource versions and reconciliation rather than arrival-order assumptions.
8. Redact observability data. Keep secrets and sensitive payload fields out of logs and support tools.

Conclusion

A webhook turns an event into an HTTP notification, giving integrations low-latency updates without constant polling. The HTTP call is the easy part. A production design verifies raw-body signatures, enforces freshness, deduplicates by event ID, handles reordering, acknowledges only after durable acceptance, processes through a queue, protects endpoint registration from SSRF, and reconciles important state. Those controls turn a callback into a dependable integration boundary.