Verifying signatures

Every delivery carries an X-Inboundr-Signature header. Verify it with your endpoint’s secret (the whsec_… value shown once when you created the endpoint) before trusting the payload.

Deliveries also still carry the original X-Inbound-Signature (no r) with an identical value, so handlers written before the rename keep working. Read X-Inboundr-Signature in new code — or use the inboundr npm package, whose readSignatureHeader accepts either.

Signature format

X-Inboundr-Signature: t=1721471400,v1=6a2f…e19b

t — the Unix timestamp when the signature was generated.
v1 — HMAC-SHA256(secret, "{t}.{rawBody}"), hex-encoded.

The signed message is the timestamp, a literal ., then the raw request body. Compute the HMAC over the exact bytes you received — don’t re-serialize the JSON.

Verify it

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=")),
  );
  const t = parts.t;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: str, header: str, secret: str) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.{raw_body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

<?php
function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(",", "&", $header), $parts);
    $expected = hash_hmac("sha256", "{$parts['t']}.{$rawBody}", $secret);
    return hash_equals($expected, $parts["v1"] ?? "");
}

Use a constant-time comparison (timingSafeEqual / compare_digest / hash_equals), not ==, to avoid timing attacks.

Reject stale deliveries

To defend against replay, reject deliveries whose timestamp t is too far from now (for example, more than 5 minutes):

const ageSeconds = Math.abs(Date.now() / 1000 - Number(t));
if (ageSeconds > 300) return false;

Reading the raw body

Frameworks that auto-parse JSON can change the bytes. Read the raw body first:

Express — express.raw({ type: "application/json" }), then JSON.parse after verifying.
Next.js route handlers — await req.text(), verify, then JSON.parse.
Fastify — enable rawBody and hash that.
PHP — read file_get_contents("php://input"), verify, then json_decode.

Start here

How Inboundr works

Recipes

Webhooks

Agents & MCP

Account

Verifying signatures

Signature format

Verify it

Reject stale deliveries

Reading the raw body

​Signature format

​Verify it

​Reject stale deliveries

​Reading the raw body

Signature format

Verify it

Reject stale deliveries

Reading the raw body