Real-Time APIs · Webhooks
Webhook Security
Signatures, secrets rotation, SSRF protection and payload safety.
Senders: sign payloads (HMAC-SHA256 or asymmetric signatures like Ed25519) including the message ID and timestamp, support secret rotation (multiple active signatures), only deliver to HTTPS URLs, and protect against SSRF — customer-supplied URLs could target your internal network or cloud metadata, so resolve and block private/link-local IPs and disable redirects. Receivers: verify in constant time, reject stale timestamps, and treat payloads as untrusted input.
Webhook threats
| Risk | Mitigation |
|---|---|
| Forged webhooks | HMAC/asymmetric signatures; verify in constant time |
| Replay attacks | Timestamp in signed content; tolerance (≈5 min); dedupe ids |
| Leaked secret | Rotation with overlapping secrets |
| SSRF via endpoint URL (sender) | HTTPS only, block private IPs, pin resolved IP, no redirects |
| Malicious payload content (receiver) | Schema validation; never trust embedded URLs blindly |
Standard Webhooks signature (HMAC-SHA256, base64):
signed_content = "{webhook-id}.{webhook-timestamp}.{raw_body}"
signature = base64(HMAC_SHA256(secret, signed_content))
header = "webhook-signature: v1,<signature> v1,<signature_with_old_secret>" # during rotation
Common pitfalls
- Signatures without timestamps (replayable forever).
- Delivering to user URLs that resolve to 169.254.169.254.
- Comparing signatures with ==.
Key points
- Signed id + timestamp + body
- Rotation-friendly
- SSRF-safe delivery
Further reading: OWASP SSRF Prevention Cheat Sheet
Practice questions
Why is SSRF a concern for webhook senders?
Answer
Customers provide the destination URL; without validation an attacker can point it at internal services or cloud metadata endpoints and make your servers request them.
How do you rotate a webhook signing secret without downtime?
Answer
Sign with both old and new secrets during an overlap window (multiple signatures in the header) so receivers can switch secrets at their own pace.
Open in the app to mark lessons complete, take notes and track your progress.