Webhook Fundamentals

Webhooks allow servers to notify clients about events in real time, eliminating the need for clients to poll for updates.

Quick Overview

Webhooks are HTTP callbacks that a server sends to a client-provided endpoint when a specific event occurs. They’re used to inform about payments, status changes, notifications, integrations, and many other events. Unlike polling APIs—where the client repeatedly asks whether anything has changed—webhooks push data actively from server to client. A solid webhook implementation accounts for security, reliability, idempotence, retry strategies, and clear error handling. Webhooks are a critical pattern for event-driven architectures and modern service integrations.

Key Components

Event Source and Target System

The event source is the server that triggers the webhook. The target system is the client endpoint that receives it. Both systems must be able to communicate over HTTP, and the target system must be publicly accessible if the server sits outside your network.

Registering a Webhook URL

The client registers a URL with the event source, specifying where webhooks should be sent. This registration typically happens via a dashboard or API. It’s important that the URL uses HTTPS and is validated to prevent tampering.

Payload and Event Format

The payload is the webhook’s content, usually in JSON. It contains information about the event: event type, timestamp, affected resource, and details. A unique event ID field helps identify duplicates.

Security and Signatures

Webhooks should be signed so the recipient can verify the message actually came from the expected source. HMAC-SHA256 signatures over the payload are a common approach. The recipient verifies the signature using a shared secret or public key.

Idempotence in Webhooks

Webhooks may be delivered multiple times due to timeouts or retries. The recipient must process events idempotently using a unique event ID. Duplicate event IDs should be ignored or discarded once already processed.

Retry Strategies

If the recipient doesn’t respond with a success code, the event source should retry the webhook. Retries should use exponential backoff to avoid overwhelming the target system. After a certain number of attempts or time window, the event source should give up and mark the event as failed.

Expected Response Codes

The target system should respond with 2xx on successful receipt. 4xx codes signal that the recipient rejects or cannot process the request. 5xx codes indicate a temporary issue warranting a retry. Wrong codes can cause events to be incorrectly retried or abandoned.

Timeouts

The event source should define a timeout after which it considers the request failed. Recipients should acknowledge webhooks quickly and perform longer processing asynchronously in the background to avoid timeouts.

Webhook Logs and Monitoring

Both sides should log webhooks, including event ID, timestamp, HTTP status code, and response time. Monitoring helps identify outages, delays, and error rates. Dashboards showing delivery status are particularly useful.

Webhook Testing and Debugging

For development, tools like ngrok, local webhook testers, or sandbox endpoints work well. They let you receive, inspect, and debug webhooks locally without needing public servers.

Practical Example

A payment service wants to notify its customers when a payment succeeds. The customer registers a webhook URL:

POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer token

{
  "url": "https://shop.example.com/webhooks/payments",
  "events": ["payment.succeeded", "payment.failed"]
}

When a payment succeeds, the payment service sends a webhook:

POST /webhooks/payments
Content-Type: application/json
X-Event-ID: evt-9876543210abcdef
X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592

{
  "eventType": "payment.succeeded",
  "eventId": "evt-9876543210abcdef",
  "timestamp": "2026-07-01T12:34:56Z",
  "data": {
    "paymentId": "pay-123456",
    "orderId": "order-7890",
    "amount": 79.97,
    "currency": "EUR"
  }
}

The recipient verifies the signature, stores the event ID, and processes the payment. It responds with 200 OK to confirm successful delivery. On timeout or 5xx error, the payment service retries with exponential backoff.

FAQ: Webhook Fundamentals

1. What is a webhook?

A webhook is an HTTP request that a server sends to a client to report an event. Unlike polling, data is pushed actively from server to client.

2. What’s the difference between webhooks and polling?

With polling, the client regularly asks the server for new data. With webhooks, the server actively notifies the client when an event occurs. Webhooks are more efficient and nearly real-time.

3. How do you register a webhook?

The client registers a URL and desired event types with the event source. This typically happens via an API endpoint or dashboard.

4. Why should webhooks use HTTPS?

HTTPS encrypts transmission and protects against eavesdropping and tampering. Unencrypted webhooks are a security risk since sensitive data or signature secrets could be exposed.

5. What is a webhook signature?

A webhook signature is a cryptographic hash of the payload. The recipient can verify the signature to ensure the message came from the expected source and wasn’t modified.

6. How does idempotence work with webhooks?

Each webhook contains a unique event ID. The recipient stores this ID and processes events with the same ID only once. This keeps processing idempotent even when retries occur.

7. What is exponential backoff?

Exponential backoff means retry intervals grow progressively longer. This prevents overwhelming the target system and gives it time to recover from temporary issues.

8. What response codes should a webhook recipient return?

Return a 2xx code on successful processing. 4xx codes mean the request is rejected, 5xx codes signal a temporary problem.

9. What happens if a webhook can’t be delivered?

The event source should retry the webhook following a retry strategy. After a defined number of failed attempts or time window, the event is marked as failed and optionally reported to an operator.

10. What is a Dead Letter Queue for webhooks?

A Dead Letter Queue stores webhooks that couldn’t be delivered after multiple attempts. It allows for later manual review or retry.

11. Should webhook processing be synchronous or asynchronous?

Recipients should acknowledge webhooks quickly and perform heavy processing in the background. This prevents timeouts and ensures reliable delivery.

12. How do you test webhooks locally?

Local webhooks can be tested with tools like ngrok, webhook.site, or local tunnels. These forward incoming requests to your local development environment.

13. What is an event ID?

An event ID is a unique identifier for a single event. It’s included in the webhook and lets the recipient detect duplicates and track events.

14. What security measures are important for webhooks?

Key security measures include HTTPS, signature verification, IP whitelisting, timestamp validation against replay attacks, and payload validation. The target system should only accept from trusted sources.

15. What is a webhook replay?

A webhook replay is resending an already-triggered webhook. It’s used to redeliver an event after an error or during testing, without repeating the original action.

Continue your API learning journey

The next article in our API learning path covers GraphQL API Development: Schemas, Resolvers, Subscriptions, and Apollo — the REST alternative offering flexible data queries and a typed schema.

Täglicher Artikel