Secure Webhooks
A public webhook endpoint must verify who sent the exact body, when it was sent, and whether the event was already processed.
Frame the problem
Security starts with a concrete asset, attacker capability and trust crossing.
Why the system fails
The handler trusts the source address or a shared URL, parses before verifying the raw body, or processes duplicate event IDs.
The important question is not “what is Secure Webhooks?” but “which assumption let untrusted data or an over-scoped identity cross external provider → privileged application event?” Trace the decision at the boundary, then constrain what can happen after the first control fails.
Design the control in layers
Start with the control closest to the interpretation or privilege boundary: Verify the provider signature over the raw body and timestamp Then add a control that reduces blast radius and telemetry that proves the decision was enforced.
The resulting design is not labelled secure. Record the identified controls, the known failure paths, the remaining exposure, and the evidence you would need during an incident.
| Prevent | Detect | Recover |
|---|---|---|
| Verify the provider signature over the raw body and timestamp · Enforce a replay window and idempotent event ID · Give the handler a narrowly scoped capability | Invalid signatures, stale timestamps and duplicate IDs | Contain the affected identity or component, scope impact from audit evidence, and preserve a regression test. |
Key points
- Asset: Integrity of externally triggered state changes.
- Boundary: External provider → privileged application event
- Primary control: Verify the provider signature over the raw body and timestamp
- Detection signal: Invalid signatures, stale timestamps and duplicate IDs
- Always ask what limits damage when the primary control fails.
Boundary control exercise
This lesson uses the shared boundary-control exercise.
Follow the attack
Safe conceptual simulation: capability → missing control → crossed boundary → asset impact.
- 1Attacker starts with: Anyone on the internet able to call the public webhook URL or replay a captured event.
- 2The handler trusts the source address or a shared URL, parses before verifying the raw body, or processes duplicate event IDs.
- 3The weak or missing boundary control is crossed: External provider → privileged application event
- 4Impact: Forged payments, account changes or repeated operations.
- Forged payments, account changes or repeated operations.
Defend, detect, recover
One prevention is a single point of security failure. Layer it and make failure observable.
- • Verify the provider signature over the raw body and timestamp
- • Enforce a replay window and idempotent event ID
- • Give the handler a narrowly scoped capability
- • Invalid signatures, stale timestamps and duplicate IDs
- • Contain the affected identity or component.
- • Scope access from audit evidence.
- • Fix the boundary and add a regression test.
- • Misconfiguration and new access paths can bypass the intended control.
- • A privileged insider or compromised control plane may still reach the asset.