← Blog

How the proxy stays out of your way

The short list of rules on Hookman's webhook hot path, and what happens when a delivery goes wrong.

Darren Royle @royletron 2 min read

A webhook proxy has one job that matters more than any other: don’t make webhooks worse. Providers like Stripe time out and retry, so anything we add to the path is paid for by every delivery. These are the rules the proxy, a Cloudflare Worker, follows.

Config comes from KV, and only KV

A webhook for hookman.dev/w/acme/payments makes the Worker read one key, route:acme/payments, from Workers KV. It holds everything needed to route: the rules and the URL of the active deployment. No database is involved.

The dashboard and API keep the real data in Postgres. When you publish a change, they write the result into KV, and the proxy only ever reads it.

No auth on the way in

Webhooks come from third parties who can’t carry our credentials. Signature checking stays your application’s job, and it still works because the request is forwarded exactly as it arrived.

Read the body once

Payload-based routing needs the JSON body, so when a rule needs it we parse it once and keep it. When the routing key is in a header or the query string, the body isn’t read first and the lookups run in parallel.

Mirror the response

The sender sees whatever your deployment answers: same status, body and headers, plus a few x-hookman-* markers. Redirects are not followed, so a 3xx goes back to the sender as it is.

Everything else happens afterwards

Analytics, log writes and payload storage run in waitUntil, after the response has gone. A slow log write never delays a delivery. Fan-out copies work the same way.

When it goes wrong

Putting a proxy in front of your webhooks means trusting it, so here is what it does when something fails.

  • Your deployment is unreachable or takes longer than 10 seconds. There is nothing to mirror, so the sender gets a 502. The payload is kept so you can replay it, and Pro and Team plans retry automatically.
  • The project doesn’t exist. The sender gets a 404 with a JSON error.
  • Hookman itself is down. Deliveries fail and the provider’s own retries take over. That is the cost of a single endpoint, and the reason the hot path is kept this small.

Why it matters

None of this is clever. It’s a short list of things not to do on the hot path, written down so we keep to them as the product grows. Features like inboxes live in separate Workers for the same reason: if they aren’t on a webhook’s path, they can’t slow it down.

More from the blog