auditing-webhook-authenticity-and-callback-trust

name	auditing-webhook-authenticity-and-callback-trust
description	Audit both directions of webhook trust: an inbound handler that acts on a payload without proving it authentic, and an outbound fetch of a caller-supplied URL that reaches internal targets. Covers inbound handlers with no signature check, a signature compared in non-constant time, a signature computed over a re-serialized body instead of the exact raw bytes, a verification result that is computed but never enforced, and no timestamp or replay defense; and outbound callback or fetch URLs validated by substring or blocklist, or by a single pre-connect lookup that a redirect or a rebind defeats. Use when reviewing code that receives a signed webhook and performs a state change, or that fetches a URL the caller controls. The inbound request or the caller-supplied URL is the source, the state-changing handler or the server-side fetch is the sink, and a missing or bypassable trust check between them is the bug.
license	MIT

Auditing webhook authenticity and callback trust: proving the caller and pinning the target

A webhook is a trust boundary in two directions and both are easy to get wrong. Inbound, an internet caller posts a payload and the handler acts on it, provisioning access or crediting a balance, as if it came from the real sender; the only thing separating the real sender from anyone is a signature check that is often absent, compared unsafely, computed over the wrong bytes, or thrown away. Outbound, the same systems fetch a URL the caller supplied, a callback target or an import link, and a server-side request to an internal address reaches things the internet cannot. You find both by tracing the inbound request to the action it drives and the caller-supplied URL to the request it makes, and asking what proof or restriction stands between.

When to use

• A handler receives a webhook or callback and performs a state change based on its payload.
• The application fetches a URL that a user registered or supplied, for a callback, import, preview, or discovery.
• You want to know whether an unauthenticated caller can forge an event or steer a server-side request inward.

Scope check

Send forged events or callback URLs only to systems you own or are authorized to test, and prove internal reach only against infrastructure in scope. A working webhook forgery or a server-side request to internal services can move money or expose credentials, so coordinate. If you can't name the authorization, stop.

The loop

1. Map inbound handlers and outbound fetches. Inventory the endpoints that receive a webhook and act on it, and the places the server fetches a caller-influenced URL. For each inbound handler, note what action it drives; for each outbound fetch, note whether the URL comes from user input. These are the two sinks the rest of the loop reasons about.

2. Check that inbound verification exists and is enforced. The handler must verify a signature over the payload with a server-held secret before it acts. The bug is a handler that never references the secret, or that computes a verification result and then proceeds regardless, or that swallows a verification error and falls through to processing. A result that is not gated on is not a check.

3. Check the comparison, the signed bytes, and replay. The signature comparison must be constant-time, or its timing leaks the expected value byte by byte. The signature must be computed over the exact raw request bytes, not a re-serialized or framework-parsed body, or a benign reordering breaks legitimate signatures and tempts a developer to weaken the check. And a timestamp within a tight window plus a stored nonce or idempotency key must stop a captured valid request from replaying.

4. Check outbound destination validation. For each caller-supplied URL, read how the destination is restricted. A substring, prefix, or suffix test on the host is bypassable by a lookalike, a userinfo segment, or a trailing dot; a blocklist of literal loopback names is bypassable by an alternate IP encoding or a private range; an unrestricted scheme lets non-web schemes reach internal services. The safe shape resolves the host and confirms the resolved address is public.

5. Check redirects and connect-time resolution. A destination validated once and then fetched can still reach an internal target if the client follows a redirect to it, or if the name resolves to a public address at validation time and an internal one at connect time. The safe shape pins the connection to the address it validated and re-validates or refuses every redirect hop.

6. Confirm and record. Confirm inbound by posting a forged event that the handler acts on, or by showing the comparison is non-constant-time, the signed bytes are wrong, or replay succeeds. Confirm outbound by steering a fetch to an internal or link-local target, or to a redirect that lands there. Kill an inbound lead if a vetted verification routine checks a raw-body signature in constant time, enforces the result, and bounds replay; kill an outbound lead if the destination is resolved, pinned to a public address, scheme-restricted, and redirect-safe, or the URL is only stored and never fetched. Record the handler or fetch, the missing check, and what it drove.

Where webhook trust leaks

• An inbound handler with no signature is an open, authenticated-looking endpoint. Anyone who knows the URL drives the action. The signature is the only thing making the sender the sender.
• The comparison and the signed bytes are where a present check still fails. A non-constant-time compare leaks the secret over time; a signature over a re-serialized body verifies the wrong thing.
• A valid request with no replay defense is reusable. Without a timestamp window and a nonce store, a captured event fires again whenever the attacker likes.
• An outbound fetch of a caller URL points inward by default. Loopback, private ranges, and the link-local metadata address are reachable unless the destination is resolved and pinned to a public one.
• A redirect is a second, unvalidated URL. Validating only the first hop lets the server be walked inward by a response it trusts.

Worked example (a confirm and a kill)

Confirm. A billing webhook handler computes a signature over the parsed and re-serialized body and compares it to the header with an ordinary equality check, then marks an invoice paid. The comparison is non-constant-time and the signed bytes differ from what the sender signed, so verification is effectively decorative; a forged event marks arbitrary invoices paid. Confirmed unauthenticated webhook forgery, critical, remediation = verify a constant-time signature over the exact raw request bytes with the server-held secret, enforce rejection on failure, and bound replay with a timestamp window and an idempotency key.

Kill. The handler passes the raw body and the signature header to a vetted verification routine that compares in constant time and enforces a timestamp tolerance, acting only on success; a separate outbound fetch resolves the caller URL, refuses private and link-local addresses, pins the connection to the resolved public address, restricts the scheme, and rejects redirects. Forged and replayed events are rejected and the fetch cannot be steered inward. Killed, kill_reason = "raw-body constant-time signature enforced with replay bounds; outbound destination resolved, pinned, scheme-restricted, and redirect-safe."

Rationalizations to reject

• "The webhook URL is secret, so only the sender knows it." -> A URL is not a credential; it leaks in logs, referrers, and history. The signature, not the obscurity of the path, authenticates the sender.
• "We verify the signature." -> Over the raw bytes or a re-serialized body, and in constant time, and is the result actually enforced? A verify that runs and is ignored protects nothing.
• "There is no replay risk, the event is idempotent." -> Only if the handler truly is; most state changes are not, and a captured valid event replays without a timestamp and nonce.
• "The callback host is on our allowlist." -> Matched how? A suffix or substring test passes a lookalike, and a validated name can still resolve or redirect inward at connect time.
• "It only fetches over the web scheme." -> To any address, including internal ones, unless the resolved address is confirmed public and the connection pinned to it.

Executing this in practice

You need the inbound handler bodies and the action each drives, the verification routine and exactly what bytes it signs and how it compares, the replay defenses, and for each outbound fetch the URL's origin and the destination-validation and redirect logic. For each inbound handler decide whether a forged or replayed event is accepted; for each fetch decide whether it can be steered to an internal target. Reading the code tells you the shape; posting a forged event or steering a fetch on a target in scope tells you whether the boundary holds.

Related

• exploiting-ssrf-to-cloud-metadata - the outbound half taken to its worst case; both trace a caller-supplied URL to a server-side request and ask what internal reach it buys.
• auditing-cors-and-cross-origin-trust - a sibling trust-boundary audit where an attacker-set value, the request origin, is trusted without proof.
• finding-fail-open-flaws - a swallowed verification error that falls through to processing is a fail-open control; both hunt a check that does not stop what it should.
• FINDING-SCHEMA.md - source = the inbound request or the caller-supplied URL, sink = the state-changing handler or the server-side fetch, evidence = the forged event or the internal target reached.