GuidesIntegrations

Webhook: the principle, and how to receive one without errors

By the Banzai Labs teamUpdated on 2 min read

Service Apayment.paidPOST{ JSON }SignedYour app200 OKOtherwise, it retriesIt tells you, you don’t have to ask
A webhook: the service sends you the event as soon as it happens, signed, and retries on failure.

The principle

Stripe, Shopify, GitHub or an e-signature service send a JSON POST to the URL you give them, for each event: payment.paid, order.created.

Four receiving rules

  1. 1Check the signatureThe service signs each message with a shared secret. No valid signature, reject.
  2. 2Answer fastA 200 right away, the processing afterwards, in a queue.
  3. 3Tolerate duplicatesKeep the ID of every event handled.
  4. 4Log everythingTo replay an event or understand an error.

Common mistakes

Mistake Consequence
No signature check Anyone can fake a payment
Long processing before answering The service assumes failure and resends
No duplicate check An order shipped twice
Assumed event order An old status overwrites the recent one

For automations, see n8n, Make or custom code and HTTP status codes.

Frequently asked questions

Webhook or API?
With an API, you ask “anything new?” at intervals. With a webhook, the service calls you when there is something new. Fewer calls, less delay.
What if my server is down?
Most services retry for a while. Also plan a resync through the API to catch up on a lost event.
Why receive the same event twice?
Because the service retries when it got no answer in time. Your code must recognise an event already handled and ignore it.

Read next

All guides