APIs & Authentication
What is a webhook?
A user-defined HTTP callback, your URL gets POSTed to whenever an event happens in someone else's system, instead of you polling for changes.
Webhooks invert the API direction. Instead of your code asking the service "anything new?" every minute, you give the service a URL, and it POSTs to that URL the moment something happens. Stripe's charge.succeeded, GitHub's push, Slack's message, every modern SaaS's "event delivered" flow, all webhooks.
Receiving webhooks well is harder than it looks. You need to verify the signature header to confirm the payload is real, return 2xx fast (long-running work goes to a background queue), tolerate duplicate deliveries (the sender retries on non-2xx), and handle out-of-order events (don't assume the timeline matches your DB state).
Sending webhooks well is also non-trivial: durable queues, exponential retries with a max attempt count, signed payloads, per-customer dead letter queues, and an admin UI for replays. Most teams underestimate how much of webhook infrastructure is on the sender side.
In the wild
- →Stripe POSTing
payment_intent.succeededto your/webhooks/stripeendpoint - →GitHub POSTing
pushevents to your CI server - →Brand.dev POSTing brand-data updates as part of an enrichment workflow
How Brand.dev uses webhook
Endpoints in the Brand.dev API where this concept comes up directly.
FAQ
Webhook vs API?
An API call is your code → their server. A webhook is their server → your code. APIs are pull, webhooks are push. Most SaaS exposes both for the same events.
How do I verify a webhook is authentic?
Compute an HMAC of the raw request body using a shared secret, and compare it to the signature header (Stripe-Signature, X-Hub-Signature, etc.). Always compare in constant time.
How do I test webhooks locally?
Use ngrok or Cloudflare Tunnel to expose your localhost to the internet, then point the webhook at the public URL.
Related terms
An Application Programming Interface, a contract that lets one program request actions or data from another in a stable, documented way.
The application protocol the web is built on, a simple request/response format for asking a server for a resource.
A server-side policy that caps how many requests a client can make in a given window, returning 429 Too Many Requests when the cap is exceeded.
An API that follows REST conventions, using HTTP methods on resource URLs to model create/read/update/delete operations.