Signature Verification
Every webhook request includes anX-Webhook-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing the payload.
How Signing Works
- ThinnestAI constructs:
{timestamp}.{raw_json_body} - Signs with HMAC-SHA256 using your endpoint’s secret
- Sends as
X-Webhook-Signature: sha256={hex_digest}
Python
FastAPI Example
Node.js
Express Example
Go
Best Practices
- Always verify signatures before processing payloads
- Check timestamps to prevent replay attacks (5 minute window)
- Use constant-time comparison (
hmac.compare_digestin Python,crypto.timingSafeEqualin Node.js) - Respond with 2xx quickly — do heavy processing asynchronously
- Handle duplicates — use
X-Webhook-Delivery-Idfor idempotency - Store the secret securely — treat it like an API key

