Skip to main content

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

  1. Khaime computes HMAC-SHA256(webhook_secret, raw_request_body)
  2. Sends the hex digest in X-Khaime-Signature
  3. 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.