Webhook Security
HMAC-SHA256 signature verification and SSRF protections.
Signature verification
Every webhook delivery is signed with HMAC-SHA256. Always verify signatures before processing events.
See the verification guide for copy-paste code in Node.js, Python, and Go.
Quick reference
Signed content: ${timestamp}.${body}
Signature header: X-VantageKit-Signature: sha256={hex_hmac}
Verification steps:
- Extract the signature and timestamp from headers
- Compute
HMAC-SHA256(secret, "${timestamp}.${body}") - Compare using a timing-safe function
- Reject if timestamp is more than 5 minutes old (replay protection)
Signing secret
Each webhook endpoint has its own signing secret, generated when the endpoint is created. The secret is shown once at creation time — store it securely.
If you lose the secret, delete the endpoint and create a new one.
SSRF protection
VantageKit validates webhook endpoint URLs to prevent Server-Side Request Forgery:
- HTTPS required — HTTP URLs are rejected
- Private IPs blocked —
localhost,127.0.0.1,10.x.x.x,172.16-31.x.x,192.168.x.x,169.254.x.x, and IPv6 private ranges - DNS rebinding mitigation — Hostnames are re-resolved at delivery time
IP allowlisting
Webhook deliveries originate from Vercel's edge network. If your firewall requires allowlisting, use Vercel's published IP ranges.
Best practices
- Verify every delivery — Never skip signature verification, even in development
- Process asynchronously — Return
200 OKquickly, then process the event in a background job - Be idempotent — Use the
X-VantageKit-Deliveryheader to deduplicate events. The same event may be delivered more than once during retries. - Log delivery IDs — Store the delivery ID for debugging and correlation with VantageKit's delivery log