Webhook: getting told when something happens instead of asking

A webhook is an HTTP request that one system sends to another when an event happens. You register a URL; the sending system posts to it when there is something to tell you. It inverts the usual arrangement, where your code asks repeatedly whether anything has changed, and it is the difference between finding out in a second and finding out on the next poll.

The concept takes a paragraph. Running webhooks in production takes rather more, because the delivery is a network request between two systems that fail independently — and almost every hard-won practice in this area exists because of that.

Receiving one properly

1. Verify the signature before doing anything else. Most senders sign the payload with a shared secret; without checking it, your endpoint accepts events from anyone who learns the URL.
2. Respond fast, with a 2xx, before processing. Take the payload, put it on a queue, return. Senders time out — often in seconds — and a slow handler looks like a failure and triggers retries.
3. Make the handler idempotent. Every serious sender retries, and duplicate deliveries are normal rather than exceptional. Key on the event id and ignore what you have already seen.
4. Do not assume order. Events can arrive out of sequence, and a design that requires created before updated will break on a bad afternoon.
5. Log the raw payload before parsing. When something is wrong at three in the morning, the request you actually received is the only useful evidence.
6. Return errors honestly. Swallowing a failure and returning 200 means the sender stops retrying and the event is gone.

Treat duplicate deliveries as certain, not possible. Retries after a timeout are the normal behaviour of every webhook sender, which means your handler will be called twice for the same event — and if that handler charges a card, sends an email or creates an order, the second call is a real incident. Storing processed event ids for a few days costs almost nothing and removes an entire class of bug.

Sending them

• Sign every payload, and document how. Recipients cannot verify what you do not explain.
• Include an event id and a timestamp, so the receiver can deduplicate and reject replays.
• Retry with exponential backoff, and stop eventually — with a way for the recipient to see what failed.
• Send a minimal payload with an id the receiver can fetch, or a full one. Both are defensible; document which, because they lead to different receiver designs.
• Version the payload. Adding a field is usually safe; changing the meaning of one is not.
• Give recipients a way to replay missed events. This is the feature people ask for after their first outage and are grateful for forever.

Webhook or polling

Webhooks are the better default when events are infrequent and latency matters — you find out immediately and waste no requests. Polling is genuinely better in two situations: when the receiver cannot expose a public endpoint at all, and when you need a guarantee that nothing was missed, since a poll re-reads state while a webhook is a one-time announcement. Many robust integrations use both: webhooks for speed, and a periodic reconciliation poll to catch whatever the webhooks lost.

Where Ettex fits

Ettex API is where webhooks from Ettex are configured, and the same practices above apply on both sides of the connection. The broader question of connecting two systems at all is covered in api integration.

The honest limits: this is a straightforward events-and-endpoints arrangement, not an integration platform. There is no visual builder, no transformation layer, no marketplace of pre-built connectors. If you want two systems joined without writing code, an integration platform is the category to shop in and we are not competing with it.