How to verify InfiQ webhook signatures
Your webhook endpoint is a public URL, so anyone can POST to it. The X-InfiQ-Signature header proves that a request came from InfiQ and wasn't changed on the way. Checking it takes a few lines, and one wrong detail, usually the raw body, makes every check fail, so this guide spells out the details.
In short
Read t and v1 from the X-InfiQ-Signature header, reject the request if t is more than 120 seconds from your clock, compute HMAC-SHA256 over the string made of t, a full stop and the raw body with your endpoint's signing key, and compare the result with v1 in constant time. Use the exact bytes you received, never JSON you parsed and encoded again.What the header contains
The header looks like t=1785573342,v1=5d41402abc… where t is the Unix time InfiQ signed the request and v1 is the hex HMAC-SHA256. After you rotate the endpoint secret a kid=<version> part appears, and during the rotation's grace window InfiQ adds v0=<hex>, a signature made with the previous key. X-InfiQ-Timestamp repeats t as a header of its own.
The four checks
Every check has to pass before you trust the payload:
- Split the header into its parts and require t and v1.
- Reject the request if t is more than 120 seconds away from your clock, so a captured request can't be replayed later.
- Compute HMAC-SHA256 over t, a full stop and the raw request body, using your endpoint's signing key.
- Compare your result with v1 (or with v0 during a rotation) using a constant-time comparison, and reject on a mismatch.
Get the signing key
The signing key is derived from your endpoint's secret, the whs_live_… value shown once when you created the endpoint. The endpoint's detail page in the dashboard shows the current verification recipe and the key to use. Store it in an environment variable such as INFIQ_WEBHOOK_KEY, and never commit it.
Verify in Node.js, Python or PHP
Each function takes the header and the raw body (and, in PHP, the key) and returns true only when every check passes:
// verify.jsimport crypto from "node:crypto";const KEY = process.env.INFIQ_WEBHOOK_KEY; // the endpoint's signing keyconst MAX_AGE = 120; // secondsexport function verifyInfiqSignature(header, rawBody) {if (!header) return false;const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")),);const t = Number(parts.t);if (!t || Math.abs(Date.now() / 1000 - t) > MAX_AGE) return false;const expected = crypto.createHmac("sha256", KEY).update(`${parts.t}.`).update(rawBody) // Buffer with the exact bytes received.digest();// v0 appears only during a secret rotation's grace window.return [parts.v1, parts.v0].filter(Boolean).some((sig) => {const given = Buffer.from(sig, "hex");return given.length === expected.length && crypto.timingSafeEqual(given, expected);});}
Why verification fails
When every request fails the check, it is almost always one of these:
- The body was parsed and encoded again. JSON.stringify(JSON.parse(body)) changes spacing and key order; check the bytes you received (express.raw, request.get_data(), php://input).
- A plain string comparison. == leaks timing information; use crypto.timingSafeEqual, hmac.compare_digest or hash_equals.
- Clock drift. If your server's clock is off, the 120-second check fails, so keep it synced with NTP.
- A secret rotation. During the grace window, accept either v1 or v0; afterwards only v1.
- The wrong key. Use the endpoint's signing key, not your API key (isk_…) and not a Meta app secret.
Test it end to end
Send yourself a signed test event and watch the check pass before real messages arrive:
curl -X POST https://api.infiq.in/v1/webhooks/test \-H "X-INFIQ-API-KEY: $INFIQ_API_KEY" \-H "Content-Type: application/json" \-d '{"event": "message.received"}'# 202 Accepted# {"id": "evt_test_1a2b", "status": "queued"}
Works with sandbox (isk_test_…) keys. The event is signed exactly like real traffic.