Webhooks vs Polling: The Four Problems Push Hands You

A webhook is an HTTP POST that arrives at your server without you asking for it. That is the whole idea. Instead of your code calling somebody else's API to find out whether a payment settled, their server calls a URL you registered, the moment it settles. Stripe, GitHub, Slack, Shopify, Twilio and roughly every other platform you will integrate with ships this, and the setup is genuinely five minutes: paste a URL into a dashboard, copy a signing secret, done.

Then the interesting part starts. Because inverting the call also inverts who owns the hard problems. When you poll, you decide when the request happens, you know it came from you, and you get exactly one answer per question you ask. When you receive a webhook you get none of those three things, and almost every webhook bug I have watched teams chase comes from assuming otherwise.

I want to walk through both models honestly, do the arithmetic on what polling actually costs, and then be specific about the four things a receiver has to handle that a poller never does. If you have never touched this layer, the piece on what an API actually is is the better starting point.

Polling is you asking. A webhook is them telling.

Polling is a loop. Every N seconds you make a request, compare the answer to the last answer, and act if it changed. It is boring in the best way: the request is authenticated with your own credentials, failures are yours to retry, and if your worker is down for an hour it simply catches up when it wakes.

The cost is that you are paying for questions with no news in them, and you learn about changes an average of half your polling interval late. Providers know this and try to soften it. GitHub's Events API sends an X-Poll-Interval header telling you how often you are allowed to poll, with a default of 60 seconds, and supports conditional requests so an If-None-Match that returns 304 Not Modified leaves your rate limit untouched.^[6] That is a real mitigation and it is worth using. It does not remove the round trip, it just makes the round trip cheap.

What it cannot fix is latency. GitHub says of that same endpoint that it is not built for real-time use and event latency can run from 30 seconds to 6 hours depending on load.^[6] Polling a system that is itself batching is two queues stacked on top of each other.

The polling bill is mostly empty requests

Do the arithmetic once and you will never argue about intervals again. Poll one resource every 60 seconds and that is 60 requests an hour, 1,440 a day, 43,800 a month. If that resource genuinely changes five times a day, 1,435 of your daily requests returned nothing. That is 287 wasted calls per real event.

Now multiply by resources. A hundred customers whose subscriptions you watch is 4.38 million requests a month to learn about maybe a few thousand real changes. You will hit a rate limit long before you hit a useful interval, which is the same wall described in how API rate limiting actually works. Tightening the interval to catch changes faster makes the ratio worse, linearly, forever.

So webhooks win the cost argument outright. I am not going to pretend otherwise. They just send you the invoice in a different currency.

Your webhook endpoint is a public write path nobody reviewed

Here is the thing I wish somebody had said to me plainly the first time. A webhook receiver is a route on your public internet surface, reachable by anyone who can guess or discover the URL, that accepts a request body and then writes to your database. No session. No API key from the caller. No user. Most teams put it through the same review as a health check, which is to say none, and then it quietly becomes the most powerful unauthenticated endpoint they run.

Stripe puts the consequence in its own documentation, and I think it is the bluntest sentence in the whole page: without verification, an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records.^[1] Read it as a threat model, because that is what it is. Your handler is a machine that turns a JSON body into an order.

The signature is what closes it. Providers HMAC the request body with a shared secret and put the digest in a header. Stripe uses Stripe-Signature, signing the timestamp, a period, and the raw JSON body with HMAC-SHA256, and tells you to ignore any scheme that is not v1 so nobody can downgrade you.^[1] Slack signs the string v0:timestamp:body with the same function.^[4] GitHub sends X-Hub-Signature-256 and keeps the old SHA-1 header around only for backward compatibility.^[2]

Two details in that verification decide whether it works. The first is the raw body. Stripe requires the exact bytes it sent, and warns that any framework that manipulates the raw body will break verification.^[1] Parse-then-re-serialize reorders a key or drops a space, the hash changes, and every legitimate event starts failing.

The second is how you compare. GitHub's docs say never use a plain equality operator, and to use crypto.timingSafeEqual or Rack's secure_compare instead, because a constant-time comparison does not leak how many leading bytes were correct.^[2] Slack gives the same instruction.^[4] A normal string compare returns early on the first mismatch, and an attacker who can measure that timing across enough requests can walk the signature one byte at a time.

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300  # Stripe's own libraries default to 5 minutes


def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp = parts.get("t")
    received = parts.get("v1")  # ignore every other scheme, including v0
    if not timestamp or not received:
        return False

    # A captured request is replayable forever without this check.
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    # Sign the RAW bytes. Re-serialized JSON produces a different digest.
    signed_payload = timestamp.encode() + b"." + raw_body
    expected = hmac.new(
        secret.encode(), signed_payload, hashlib.sha256
    ).hexdigest()

    # compare_digest, never ==. A byte-by-byte compare leaks the answer.
    return hmac.compare_digest(expected, received)

The same event will arrive twice

Webhook delivery is at-least-once. Not exactly-once. Nobody sells exactly-once, because it does not exist over an unreliable network, for the same reason covered in message queue delivery guarantees.

The duplicate has a boring cause. Your handler receives the event, does the work, and then your 200 gets lost, or arrives after the deadline. The provider saw a failure. It retries. The work happens again. Stripe says directly that endpoints might occasionally receive the same event more than once, and tells you to log the event IDs you have processed and skip the ones you have seen.^[1] GitHub gives you X-GitHub-Delivery for the same purpose, and notes that a redelivered webhook keeps its original value.^[3]

So the handler has to be idempotent, and the deduplication has to be a unique constraint in your database, not a set in memory. Two retries can land on two servers in the same second. The pattern is the same one in idempotency keys and how they make retries safe: insert the event ID first, let the database reject the second insert, and treat that rejection as success.

If you take one implementation detail from this piece, take that one. A read that checks whether the event was already processed, followed by a write that records it, is a race condition wearing the costume of a safety check.

And it will arrive in the wrong order

Stripe does not hedge here either: it does not guarantee delivery of events in the order they were generated. Its own example is creating a subscription, which fires customer.subscription.created, invoice.created, invoice.paid and charge.created, and any of those can reach you first.^[1] Worse, Stripe warns you not to sort by the created timestamp, because snapshot events record it in whole seconds and distinct events routinely share one.^[1]

That kills the mental model most people bring to this, which is that a webhook stream is an ordered log you can replay. It is not. It is a set of notifications with no promised sequence.

The way I handle it is to stop treating the payload as truth. An event is a hint that something changed. On receipt, read the current state of the object back from the API and reconcile against that. It costs one extra request per event, which is nothing next to the 1,440 you were making before, and it makes ordering irrelevant by construction. Stripe suggests the same move, retrieving the missing objects yourself when an event arrives early.^[1]

Return 200 first, do the work after

Every provider gives you a deadline, and they are shorter than people expect. Slack requires an HTTP 2xx within three seconds.^[5] GitHub expects a 2xx within 10 seconds and terminates anything slower, marking the delivery failed.^[3] Stripe lists a timeout as one of its standard delivery errors and tells you to defer complex logic and return immediately.^[1]

Miss the deadline and you do not just lose one event. You get retried. Slack retries three times, nearly immediately, then after one minute, then after five.^[5] Stripe retries for up to three days with exponential backoff in live mode.^[1]

The correct handler is almost insultingly small: verify the signature, write the raw event to a queue or an events table, return 200. Everything else is a background worker's job. Stripe recommends processing events with an asynchronous queue and points out the scaling reason, which is that a spike (every subscription in your book renewing on the first of the month) will otherwise overwhelm your endpoint hosts.^[1] GitHub gives the same advice in the same words.^[3]

What I would actually build

Push wins, and it is not close, once you are past a handful of resources. But adopt it with your eyes open, because you are trading a request bill for a correctness bill.

1. Verify the signature over the raw body, with a constant-time compare, before anything else. Use the provider's library. Treat the endpoint as an unauthenticated write path in your threat model, because it is one.
2. Persist the raw event and return 200 in one step. A unique index on the event ID gives you deduplication for free, and the insert failing is your success case.
3. Never depend on order. Use the event as a signal to re-read current state from the API, not as the state itself.
4. Keep a reconciliation poll running anyway. Once an hour, not once a minute. Providers drop deliveries during incidents, and Slack describes its own Events API as best-effort. The slow poll is the net under the fast push.

That last one is the part teams skip, and it is the one I would defend hardest in a design review. Webhooks and polling are not rivals. Push is the fast path and poll is the audit. Ship both, then go look at your webhook route with the same suspicion you would give a public signup form, because architecturally it is closer to one than to anything else you run.