Webhooks
Verifying signatures
Verify the Intrio-Signature header with HMAC-SHA256 in Node, Python and PHP, with Next.js and Express examples.
Available on Growth and above.
Every delivery is signed so you can check it came from Intrio and wasn't changed or replayed.
Header
Intrio-Signature: t=1763633700,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd- Split the header on
,. Taket(Unix seconds) and everyv1value. - Reject the event if
tis more than 5 minutes from your clock. - Compute the hex HMAC-SHA256 of
<t>.<raw body>using your full secret, including thewhsec_prefix, as the key. - Accept if it equals any
v1value, using a constant-time comparison.
Verify
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 5 * 60;
/** Returns true if the raw body was signed with your secret in the last 5 minutes. */
export function verifyIntrioSignature(rawBody: string, header: string | null, secret: string): boolean {
if (!header) return false;
let t = 0;
const signatures: string[] = [];
for (const part of header.split(",")) {
const [k, v] = part.split("=", 2);
if (k === "t") t = Number(v);
if (k === "v1" && v) signatures.push(v);
}
if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
// During a secret rotation there are two v1 values; accept either.
return signatures.some((sig) => {
const got = Buffer.from(sig, "hex");
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
});
}Handle
// app/api/intrio/webhooks/route.ts
import { verifyIntrioSignature } from "@/lib/intrio-signature";
export async function POST(req: Request) {
const raw = await req.text(); // the raw body, before any JSON parsing
if (!verifyIntrioSignature(raw, req.headers.get("intrio-signature"), process.env.INTRIO_WEBHOOK_SECRET!)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(raw);
// Deduplicate: retries reuse the same id.
if (await alreadyHandled(event.id)) return new Response("ok");
switch (event.type) {
case "referral.created":
await createCrmDeal(event.data.referral, event.data.partner);
break;
case "reward.payable":
await notifyFinance(event.data.reward);
break;
}
await markHandled(event.id);
return new Response("ok");
}Rotating the secret#
Rotate a secret from Webhooks. For 24 hours after rotating, each delivery carries two v1 signatures, one with the new secret and one with the old, so you can deploy the new secret without dropping events. Code that accepts any matching v1 handles this automatically.
Last updated 20 November 2026. Building with an AI assistant? Point it at /docs/llms-full.txt.