Jan Mikoláš
Glossary
Webhook
A webhook avoids repeated polling. It does not, however, guarantee that an event will be delivered exactly once or in order.
Short definition
The recipient receives the event instead of having to request it.
With polling, a client repeatedly asks an API whether anything has changed. With a webhook, the provider sends an HTTP request to a callback URL registered by the recipient—for example, when a payment gateway confirms a payment or a carrier changes the status of a shipment.
A webhook is neither a persistent connection nor a message delivered exactly once. Each provider has its own rules for payload format, timeouts, signatures, retries, and manual redelivery. A recipient must therefore never modify an order merely because arbitrary JSON arrived at a public endpoint.
Use cases
When a webhook makes sense
Webhooks are suitable for announcing a change that another system should act on without unnecessary delay.
- confirming, declining, or refunding a payment
- receiving a new marketplace order or a change to its status
- passing on information about a shipment or its delivery
- announcing a completed import, build, or other asynchronous job
- starting a follow-up synchronisation while the source API remains authoritative for the data
Practical example
A shipment status change from a carrier
The carrier sends a shipment.delivered event with a delivery ID and shipment number. The endpoint verifies the signature and timestamp against the original body, then stores the event ID with a unique constraint and queues the change within a single transaction. Only then does it return 204.
The worker finds the order by shipment number, verifies that the new change makes sense given its current state, and records it. A second delivery of the same event is safely acknowledged, but does not create another change or send another email.
How it works
Receiving an event safely in five steps
Receipt should be fast, traceable, and separate from slow business processing.
- Sending the event The provider creates the payload, event ID, timestamp, and a signature according to its protocol.
- Capturing the raw body The endpoint reads the original body bytes and headers before decoding or reformatting the data.
- Verifying authenticity It verifies the signature according to the provider documentation using a constant-time comparison and, where applicable, checks that the timestamp is recent enough.
- Durable acceptance Within a transaction, it stores the delivery ID and creates a job or record for further processing; a unique constraint prevents concurrent duplicates.
- Prompt acknowledgement It returns the expected 2xx response, then performs the import asynchronously and idempotently.
Key concepts
Authenticity, retries, and event state
Each safeguard serves a different purpose. None covers the entire flow on its own.
HMAC signature
An HMAC over the exact data defined by the provider—often the raw payload and timestamp—proves that the message was created by someone holding the secret and that the body was not changed. It does not make the data confidential or replace HTTPS.
Timestamp and replay
An attacker may try to replay a previously valid signed message. Checking a short time window and the event ID, together with durable deduplication, limits both replays and ordinary retries.
Event ID and business identity
The delivery ID prevents the same message from being processed twice. For an order or payment, idempotence based on the external business identity is also advisable.
Timeout and redelivery
A slow response or outage can trigger another delivery. HTTP 200 or 204 acknowledges receipt of the request, not completion of the entire import.
Benefits and limitations
Faster responses, but greater responsibility for the recipient.
Benefits
- less unnecessary polling and faster notification of changes
- retries can overcome a short recipient outage
- separation of HTTP receipt from a slow import or call to another service
- a traceable record of each specific event
Common mistakes
- accepting a payload without verifying its signature and timestamp
- verifying the signature against re-serialised JSON
- returning 2xx before storing the event durably
- assuming a single delivery or correct delivery order
- retaining an old secret without managed rotation
Scope
A webhook should announce a change, not carry an entire synchronous process.
An endpoint should not call several external services, generate documents, and wait for a long import within a single HTTP response. This invites timeouts, repeat deliveries, and results that are difficult to trace. A better approach is to accept the event safely after verification and pass it to a worker.
The source system can remain the source of truth. If events arrive out of order or their meaning is unclear, the worker retrieves the current state through the API. This is safer than deriving order state solely from the sequence of notifications.
What to consider
A webhook endpoint is part of the system security boundary.
Signature rules, time tolerance, and error behaviour must follow the documentation of the specific provider.
- HTTPS, secure storage, and rotation of secrets without logging them
- the raw body, expected algorithm, and constant-time signature comparison
- an event ID and database-level protection against duplicates
- a prompt 2xx response only after durable acceptance of the message
- a correlation ID, delivery history, and controlled manual retries
Common questions
What a webhook does not guarantee
Is a webhook the same as a REST API?
No. A webhook is an HTTP event notification initiated by the provider. A REST API usually describes client-initiated interaction with resources.
Is verifying the HMAC signature enough?
No. You need HTTPS, the raw payload used correctly, constant-time comparison, a timestamp where applicable, and delivery deduplication in every case.
Should I return 2xx only after the import has finished?
Usually not. Once the event has been verified and accepted durably, it is better to acknowledge delivery promptly and process the business work separately.
Can a webhook arrive more than once or out of order?
Yes. Retries, timeouts, and manual redelivery are common. The recipient must design processing to be idempotent and verify state with the source when necessary.
How I design integration flows in practice
I separate accepting an event from completing it safely.
For orders, inventory, and external services, I address the contract, validation, duplicate deliveries, retries, and traceable error states.