FleetDeckDocs

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.

  1. Read the raw request bytes. Verifying JSON you parsed and re-serialized will fail.
  2. Reject a t more than 300 seconds from your clock to block replays.
  3. Compare in constant time.
  4. 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 "", 204

Test 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.