Verifying signatures

Every delivery carries a Routeur-Signature header: an HMAC-SHA256 of the delivery’s timestamp and raw body, keyed with your subscription’s signing secret. Recompute it over the exact bytes you received, compare in constant time, and reject timestamps far from your clock. The functions below were checked against a signature produced by Routeur’s own signing code.

Headers

Header	Example	Meaning
`Routeur-Signature`	`t=1790532613,v1=3e0fef4b…b0ce`	`t` is the Unix time in seconds when this attempt was signed. `v1` is the lowercase hex HMAC-SHA256, 64 characters.
`Routeur-Delivery`	`48213`	The delivery id, unchanged across retries. Use it to drop repeats.

The header matches ^t=[0-9]+,v1=[0-9a-f]{64}$. There is one signature per delivery; there is no list of alternatives and no other version than v1.

The algorithm

Take the raw request body as bytes, before any JSON parsing or re-encoding.
Build the signing string: the decimal t, a single ., then the body bytes.
Compute HMAC-SHA256 with the key set to your secret as ASCII, the whole string including the whsec_ prefix.
Hex-encode the digest in lowercase and compare it with v1 using a constant-time comparison.
Reject the delivery when |now − t| is larger than your tolerance. Five minutes is a sensible default.

Slack subscriptions are signed the same way over the Slack body.

Worked example

With this secret and timestamp:

secret = whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
t      = 1790532613

and this body as one line with no trailing newline (1339 bytes):

{"type":"lead.executable","version":"2026-09-15","created_at":"2026-09-27T18:10:13Z","graph_run":4812,"lead":{"relation":"equivalent","cross_venue":true,"left":{"venue":"kalshi","id":"KXNFLGAME-26SEP27KCLV-KC","title":"Kansas City at Las Vegas winner?"},"right":{"venue":"polymarket","id":"nfl-kc-lv-2026-09-27-kc","title":"Chiefs vs. Raiders: Chiefs win"},"legs":[{"venue":"kalshi","market_id":"KXNFLGAME-26SEP27KCLV-KC","side":"no","ask_usd":"0.30"},{"venue":"polymarket","market_id":"nfl-kc-lv-2026-09-27-kc","side":"yes","ask_usd":"0.64"}],"depth":{"pairs":"60","cost_usd":"56.4","fees_usd":"0.89","net_usd":"2.71","limited_by":"depth","executable":true,"observed_at":"2026-09-27T18:10:12Z","issues":["estimated: kalshi KXNFLGAME-26SEP27KCLV-KC no fee is the series rate × contracts × p × (1 − p), rounded up to the cent per leg"]},"caveats":["estimated: kalshi KXNFLGAME-26SEP27KCLV-KC no fee is the series rate × contracts × p × (1 − p), rounded up to the cent per leg","unverified: top-of-book depth is unknown; asks are discovery observations","estimated: Kalshi standard 0.07 taker fee for one contract; series fee multipliers and rounding across quantities are not applied","unverified: the covering payout assumes the event settles normally; postponement, cancellation and disputes settle differently across venues"]}}

the header is:

Routeur-Signature: t=1790532613,v1=3e0fef4bac5524301d9f37cca1382b3d0312fe1681347ae3d31a0e9f0dabb0ce

Save the body to body.json and reproduce the digest from a shell:

SECRET=whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
T=1790532613
printf '%s.%s' "$T" "$(cat body.json)" | openssl dgst -sha256 -hmac "$SECRET"
# 3e0fef4bac5524301d9f37cca1382b3d0312fe1681347ae3d31a0e9f0dabb0ce

Use the same inputs to test your own implementation before pointing a subscription at it.

Code

Each function takes the raw body, the header value, the secret and a tolerance, and returns whether the delivery is authentic and recent. The now argument exists so you can test against the worked example with a fixed clock; leave it out in production.

import hashlib
import hmac
import time


def verify(raw_body: bytes, signature: str, secret: str, tolerance_seconds: int = 300, now: float | None = None) -> bool:
    """Return True when the Routeur-Signature header signs raw_body with secret and is recent."""
    parts = {}
    for part in signature.split(","):
        key, _, value = part.partition("=")
        parts[key.strip()] = value.strip()
    try:
        t = int(parts["t"])
        v1 = bytes.fromhex(parts["v1"])
    except (KeyError, ValueError):
        return False
    if abs((time.time() if now is None else now) - t) > tolerance_seconds:
        return False
    expected = hmac.new(secret.encode(), str(t).encode() + b"." + raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(expected, v1)

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

/** Returns true when the Routeur-Signature header signs rawBody (a Buffer) with secret and is recent. */
export function verify(rawBody, signature, secret, toleranceSeconds = 300, now = Date.now() / 1000) {
  const parts = {};
  for (const part of signature.split(',')) {
    const [key, ...rest] = part.split('=');
    parts[key.trim()] = rest.join('=').trim();
  }
  const t = Number.parseInt(parts.t ?? '', 10);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;
  if (Math.abs(now - t) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, 'hex'));
}

package routeurverify

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

// Verify reports whether the Routeur-Signature header signs rawBody with
// secret and was produced within tolerance of now.
func Verify(rawBody []byte, signature, secret string, tolerance time.Duration, now time.Time) bool {
	var t, v1 string
	for _, part := range strings.Split(signature, ",") {
		key, value, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch key {
		case "t":
			t = value
		case "v1":
			v1 = value
		}
	}
	seconds, err := strconv.ParseInt(t, 10, 64)
	if err != nil {
		return false
	}
	if age := now.Sub(time.Unix(seconds, 0)); age > tolerance || age < -tolerance {
		return false
	}
	got, err := hex.DecodeString(v1)
	if err != nil || len(got) != sha256.Size {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(rawBody)
	return hmac.Equal(mac.Sum(nil), got)
}

In a handler

Read the body before anything parses it, verify, acknowledge, then do the work.

import os
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["ROUTEUR_WEBHOOK_SECRET"]
seen = set()  # use your database in production


@app.post("/routeur")
def routeur():
    raw = request.get_data()  # bytes, unparsed
    if not verify(raw, request.headers.get("Routeur-Signature", ""), SECRET):
        return "", 400
    delivery = request.headers.get("Routeur-Delivery")
    if delivery in seen:
        return "", 200  # a retry of something already handled
    seen.add(delivery)
    event = request.get_json()
    if event["type"] == "lead.executable":
        handle_lead(event)
    return "", 200

import express from 'express';
import { verify } from './verify.mjs';

const app = express();
const secret = process.env.ROUTEUR_WEBHOOK_SECRET;
const seen = new Set(); // use your database in production

app.post('/routeur', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('Routeur-Signature') ?? '', secret)) return res.sendStatus(400);
  const delivery = req.get('Routeur-Delivery');
  if (seen.has(delivery)) return res.sendStatus(200);
  seen.add(delivery);
  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'lead.executable') handleLead(event);
  res.sendStatus(200);
});

package main

import (
	"encoding/json"
	"io"
	"net/http"
	"os"
	"sync"
	"time"

	"example.com/routeurverify"
)

var (
	secret = os.Getenv("ROUTEUR_WEBHOOK_SECRET")
	seen   sync.Map // use your database in production
)

func routeur(w http.ResponseWriter, r *http.Request) {
	raw, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
	if err != nil || !routeurverify.Verify(raw, r.Header.Get("Routeur-Signature"), secret, 5*time.Minute, time.Now()) {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	if _, dup := seen.LoadOrStore(r.Header.Get("Routeur-Delivery"), true); dup {
		w.WriteHeader(http.StatusOK)
		return
	}
	var event struct{ Type string `json:"type"` }
	json.Unmarshal(raw, &event)
	if event.Type == "lead.executable" {
		go handleLead(raw)
	}
	w.WriteHeader(http.StatusOK)
}

Frameworks that parse JSON before your handler runs change the bytes, and re-serializing the parsed object does not reliably give them back: the delivered body’s key order and whitespace are not guaranteed to match any serializer. Always verify the bytes as received.

Timestamps and replay

t is set when each attempt is signed, not when the event was created. A retry can arrive up to about an hour after created_at with a fresh t, so compare t with your clock, never with created_at.
A captured delivery can be replayed for as long as your tolerance allows. To close that window, record every Routeur-Delivery id you accept and ignore repeats; the id is also what makes retries idempotent.
Keep your endpoint’s clock synchronized. If you must accept a wider skew, widen the tolerance rather than dropping the check.

Webhooks overview: delivery headers, retries and endpoint requirements.
lead.executable: the body being signed.
ping: a signed test delivery to check your verifier end to end.

Get started

Concepts

Agents & MCP

Webhooks

Reference

Verifying signatures

Headers

The algorithm

Worked example

Code

In a handler

Timestamps and replay

Headers

The algorithm

Worked example

Code

In a handler

Timestamps and replay

Related