Webhook Signature Verification
Every webhook request includes an X-Khaime-Signature header containing an HMAC-SHA256 hash of the raw request body, signed with your webhook secret.
Always verify signatures before processing webhooks to prevent spoofed events.
How It Works
- Khaime computes
HMAC-SHA256(webhook_secret, raw_request_body)
- Sends the hex digest in
X-Khaime-Signature
- You recompute the same hash using the raw request body and compare
Use the raw request body (not a re-serialized version) for signature verification. Re-serializing JSON can change key ordering or whitespace, causing verification to fail.
Implementation
Use constant-time comparison (timingSafeEqual, compare_digest, hash_equals) to prevent timing attacks. Never use === or == for signature comparison.