Skip to main content

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing the payload.

How Signing Works

  1. ThinnestAI constructs: {timestamp}.{raw_json_body}
  2. Signs with HMAC-SHA256 using your endpoint’s secret
  3. 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_digest in Python, crypto.timingSafeEqual in Node.js)
  • Respond with 2xx quickly — do heavy processing asynchronously
  • Handle duplicates — use X-Webhook-Delivery-Id for idempotency
  • Store the secret securely — treat it like an API key