Skip to content
Meta Business PartnerDeveloper how-to

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.

X-InfiQ-Signature: t=…,v1=…
Header
HMAC-SHA256, hex
Algorithm
t + "." + the raw body
Signed string
120 seconds
Maximum age
Constant time
Comparison
kid=…, plus v0 during the grace window
Rotation

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.js
import crypto from "node:crypto";
const KEY = process.env.INFIQ_WEBHOOK_KEY; // the endpoint's signing key
const MAX_AGE = 120; // seconds
export 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.

Get your InfiQ API key

Frequently asked questions

Is the InfiQ signature the same as Meta's X-Hub-Signature-256?+
No. Meta signs the body alone with your app secret and sends sha256=<hex> in X-Hub-Signature-256. InfiQ signs the timestamp and the body together with your endpoint's key, which also stops replays. With InfiQ you check only InfiQ's header.
Why does my signature check fail in Express?+
Usually because express.json() parsed the body before your check saw it. Mount express.raw({ type: "application/json" }) on the webhook route and pass the raw Buffer to the check.
What should my endpoint return when the signature is wrong?+
A 4xx such as 401, without processing the payload. Don't log the full body of rejected requests, and alert if many arrive, since that can mean someone is probing the endpoint.
Do I still need HTTPS if I verify signatures?+
Yes. The signature proves who sent the request and that it wasn't altered, while HTTPS keeps the message content private on the way. Use both.