## glossary

What is Webhook?

A webhook is a mechanism through which one system automatically notifies another when an event happens. Instead of your server constantly asking "has anything changed yet?", it registers a URL and waits — when the event occurs, the other system sends an HTTP request to that URL with the data.

Hence the classic description: a webhook is an API in reverse. With a traditional API, you are the caller; with a webhook, you are the one being called.

Polling versus webhook

Without a webhook, the alternative is polling: querying the API at regular intervals to check for changes. The cost is high — if you poll every minute and the event happens once a day, 1,439 calls were wasted, and the news can still arrive up to a minute late.

What arrives at your endpoint when a payment is approved
POST /webhooks/pagamentos HTTP/1.1
Content-Type: application/json
X-Signature: sha256=9f86d081884c7d659a2f...

{
  "evento": "pagamento.aprovado",
  "id": "pay_8fk29dl",
  "valor": 14900,
  "moeda": "BRL",
  "criado_em": "2026-07-18T09:12:44Z"
}

Rules for receiving webhooks safely

Your webhook URL is public — anyone can discover it and send fake data. That makes a few precautions non-optional:

  • Validate the signature. Serious providers sign the request body with a shared secret (HMAC). Recompute the hash and compare it before trusting any data.
  • Respond fast, process later. Return 200 in milliseconds and push the heavy work onto a queue. Providers usually treat a timeout as a failure and resend.
  • Handle duplicates. Redeliveries happen. Use the event ID to guarantee idempotency — processing the same webhook twice must not charge the customer twice.
  • Never trust the payload alone. For sensitive operations, query the provider’s API to confirm the real state before acting.
  • Require HTTPS. Event data usually contains sensitive information.

Where webhooks are used

Payment gateways announcing that a charge was approved or refunded. GitHub triggering the CI pipeline on every push. Email platforms reporting that a message bounced. Automation tools like n8n, Zapier and Make run almost entirely on webhooks — the topic comes up closely in the article on chatbot automation tools.

Testing during development

The challenge of developing with webhooks is that localhost is not reachable from the internet. The usual solution is a tunnel — tools like ngrok or Cloudflare Tunnel expose your local machine on a temporary public URL, letting you receive real events during development.

## faq

Frequently asked questions

What is the difference between a webhook and an API?

The direction of the call. With an API, you make the request whenever you want the data. With a webhook, the remote server makes the request to you when the event happens. Webhooks are push; traditional APIs are pull.

What if my server is down when the webhook arrives?

Most providers implement retries with progressive backoff, trying again for minutes or hours. Even so, it is prudent to log every event received and to offer a reconciliation mechanism that queries the provider’s API to recover lost events.

Does a webhook need to return any content?

No. A 2xx status code is enough to confirm receipt. The response body is usually ignored by the provider — what matters is responding quickly and with a success status.