Webhooks & Message Queues

You already know how to call an API: you send a request, you wait, you get a response back. That model is everywhere, and it works — until the thing you care about hasn't happened yet. The payment will clear sometime in the next minute. The video will finish encoding eventually. Ten thousand orders just landed in the same second and you can't process them all right now. The request/response model has no good answer for "later," and that's the gap this guide fills.

There are two tools for "later," and people constantly confuse them. A webhook is how another company's system tells yours that something happened, by calling a URL you gave them. A message queue is how your own services hand work to each other without waiting around. Both are about events and asynchronous work — but they solve different problems, and reaching for the wrong one makes a mess. By the end of this guide you'll know which is which, how each actually works under the hood, and the handful of gotchas (signatures, duplicates, retries) that bite everyone the first time.

How to read this

Need to wire up a webhook right now? Jump to Phase 1: Push vs Pull — it's a complete walkthrough of registering a URL and verifying the events are real.
Want it to finally make sense? Read in order. Phase 1 and 2 build the two mental models, and Phase 3 puts them side by side and names the traps.

The phases

Push vs Pull: Webhooks — polling wastes effort; a webhook flips it so the other service calls your URL when something happens. How to register, what a delivery looks like, and how to verify it's genuine.
Message Queues — a to-do list between your own services. A producer drops a message, a consumer picks it up when ready. Decoupling, absorbing spikes, and surviving outages.
When to Use Which (and the Gotchas) — webhooks for cross-system notifications, queues for internal async work. Delivery guarantees, why duplicates happen, idempotency, retries, ordering, and dead-letter queues — at a gentle level.

This guide stops at the mental models and the everyday traps. The deep operational material — partitioning for throughput, exactly-once semantics, choosing a specific broker, and event-sourcing as an architecture — is deferred to a follow-up guide so this one stays a thing you can read in a sitting.

Related guides: REST APIs, Explained · Designing APIs That Last