Integrations
Verify webhook signatures
Prove a request came from FleetDeck and is fresh before acting on it.
Signature scheme
Each generic webhook request carries X-FleetDeck-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of the string <t>.<raw body> keyed with your whsec_… signing secret.
- Read the raw request bytes. Verifying JSON you parsed and re-serialized will fail.
- Reject a t more than 300 seconds from your clock to block replays.
- Compare in constant time.
- Then drop duplicates by X-FleetDeck-Delivery; retries keep the same id but get a fresh t and signature.
Node.js
verify-fleetdeck.js
import { createHmac, timingSafeEqual } from "node:crypto";
/** Returns true only for a fresh, correctly signed FleetDeck delivery. */
export function verifyFleetDeck(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(String(header ?? "").split(",").map(part => {
const i = part.indexOf("=");
return [part.slice(0, i).trim(), part.slice(i + 1).trim()];
}));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
return timingSafeEqual(Buffer.from(parts.v1, "hex"), expected);
}Express receiver
import express from "express";
import { verifyFleetDeck } from "./verify-fleetdeck.js";
const app = express();
const seen = new Set(); // use a database or cache with a TTL in production
// express.raw keeps the exact bytes FleetDeck signed. Do not use express.json() on this route.
app.post("/fleetdeck", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!verifyFleetDeck(raw, req.get("X-FleetDeck-Signature"), process.env.FLEETDECK_WEBHOOK_SECRET)) return res.sendStatus(401);
const delivery = req.get("X-FleetDeck-Delivery");
if (seen.has(delivery)) return res.sendStatus(204); // retry of a delivery you already handled
seen.add(delivery);
const event = JSON.parse(raw);
res.sendStatus(204); // answer within 10 seconds, then do slow work
queueMicrotask(() => console.log(event.event, event.run?.status));
});
app.listen(3000);Python
verify_fleetdeck.py
import hashlib
import hmac
import time
def verify_fleetdeck(raw_body: bytes, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
"""Returns True only for a fresh, correctly signed FleetDeck delivery."""
parts = dict(part.strip().split("=", 1) for part in (header or "").split(",") if "=" in part)
try:
t = int(parts.get("t", ""))
except ValueError:
return False
if abs(time.time() - t) > tolerance_seconds:
return False
signed = f"{t}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Flask receiver
import os
from flask import Flask, abort, request
from verify_fleetdeck import verify_fleetdeck
app = Flask(__name__)
@app.post("/fleetdeck")
def fleetdeck():
# request.get_data() is the raw body; never re-serialize request.json before verifying.
if not verify_fleetdeck(request.get_data(), request.headers.get("X-FleetDeck-Signature", ""), os.environ["FLEETDECK_WEBHOOK_SECRET"]):
abort(401)
event = request.get_json()
print(event["event"], request.headers["X-FleetDeck-Delivery"])
return "", 204Test your receiver
Press Send test on the alert. A correct receiver accepts the webhook.test event and the Alerts tab shows “Test delivered (HTTP 2xx)”. Return 401 for a bad signature; that is a permanent failure and is not retried.
