Verify webhook signatures

SchedStack signs every delivery so your endpoint can prove the request came from us and not an attacker who learned your URL. Delivery is at-least-once: the same occurrence can arrive more than once (retries, reclaims after a crash). The signature plus the Idempotency-Key header are what make that safe — verify the signature, then dedup on the key before you act.

This is a static guarantee you implement on your side. Read it once, copy a receiver below, and you are done.

What we send

On each delivery attempt, SchedStack sets these request headers:

Header	Example	Meaning
Sched-Signature	t=1719460800,v1=8f3c…	Timestamp + one or more HMAC signatures. Omitted entirely if the schedule has no signing secret — see Unsigned deliveries.
Sched-Timestamp	1719460800	Unix seconds when we signed. Equals the t inside Sched-Signature.
Sched-Delivery-Id	dlv_2a9f…	Stable id for this delivery.
Sched-Attempt	1	Attempt counter for this occurrence (a decimal integer, 1-based; increments on retry).
Idempotency-Key	evt_42	Stable across retries and reclaims of the same occurrence. Dedup on this. Falls back to the delivery id when you did not supply one.

The Sched-Signature value is a comma-separated list, no spaces:

Sched-Signature: t=<unix_seconds>,v1=<hex>[,v1=<hex>...]

• t — the Unix timestamp (seconds) we signed at.
• v1 — a hex-encoded HMAC-SHA256 signature. There is one v1 per active signing secret. During a secret rotation you will see two. Accept the request if any v1 verifies against the secret you hold.

The signed string

We compute the signature over this exact byte string:

{timestamp}.{delivery_id}.{attempt}.{METHOD}.{path}.{body}

Concatenated literally, joined by ., with the raw request body appended last:

• {timestamp} — the t value (same integer as Sched-Timestamp).
• {delivery_id} — the Sched-Delivery-Id value.
• {attempt} — the Sched-Attempt value, used verbatim as its decimal string.
• {METHOD} — the HTTP method, uppercased (POST, PUT, …).
• {path} — the URL-escaped path of your endpoint, with no query string (defaults to /).
• {body} — the raw request body bytes, exactly as received, before any JSON parsing.

The signature is then HMAC-SHA256(secret, signed_string), hex-encoded.

Read the raw body first

You must HMAC the exact bytes of the request body. If your framework parses JSON and re-serializes it, key order and whitespace change and the signature will never match. Read the raw body before parsing — every example below does this.

Verify a delivery

1. Parse t and every v1 out of the Sched-Signature header.

2. Reject replays. If |now − t| exceeds your tolerance, reject with 400. We recommend 300 seconds.

3. Rebuild the signed string from this request: t, Sched-Delivery-Id, Sched-Attempt, the uppercased method, the escaped path (no query string), then the raw body bytes.

4. Compute HMAC-SHA256(your_secret, signed_string) and hex-encode it.

5. Constant-time compare your result against each v1. Accept if any matches. (Constant-time compare avoids leaking the secret through timing.)

6. Dedup on Idempotency-Key before you act on the payload. Only now is it safe to JSON-parse.

Order matters

Verify the signature first, dedup second, parse and act last. A request that fails signature verification should never reach your idempotency store or your business logic.

Runnable receivers

Each example reads the raw body, rejects stale timestamps, accepts any matching v1, and dedups on Idempotency-Key. Replace the in-memory dedup stub with a durable store (a unique constraint on the key, Redis SETNX, etc.).

Node (Express)

import express from "express";
import crypto from "node:crypto";

// The signing secret you configured for the schedule, as raw bytes.
const SIGNING_SECRET = process.env.SCHEDSTACK_SIGNING_SECRET;
const TOLERANCE_SECONDS = 300;

const app = express();

// Capture the RAW body. Do NOT use express.json() ahead of this route — it
// would consume the stream and you would lose the exact bytes you must sign.
app.use(express.raw({ type: "*/*" }));

// Stub: replace with a durable, atomic check (DB unique key, Redis SETNX, …).
const seen = new Set();
const alreadyProcessed = (k) => seen.has(k);
const markProcessed = (k) => seen.add(k);

app.post("/webhooks/sched", (req, res) => {
  const header = req.get("Sched-Signature");
  if (!header) return res.status(400).send("missing signature"); // unsigned delivery

  // 1. Parse t and every v1.
  let t;
  const v1s = [];
  for (const part of header.split(",")) {
    const [k, v] = part.trim().split("=");
    if (k === "t") t = Number(v);
    else if (k === "v1" && v) v1s.push(v);
  }
  if (!Number.isFinite(t) || v1s.length === 0) {
    return res.status(400).send("bad signature header");
  }

  // 2. Reject stale timestamps (replay protection).
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > TOLERANCE_SECONDS) {
    return res.status(400).send("timestamp out of tolerance");
  }

  // 3. Rebuild the signed string. body is a Buffer of the raw bytes.
  const deliveryId = req.get("Sched-Delivery-Id");
  const attempt = req.get("Sched-Attempt");
  const method = req.method.toUpperCase();
  const path = new URL(req.originalUrl, "http://placeholder").pathname; // escaped, no query
  const body = req.body;
  const signed = Buffer.concat([
    Buffer.from(`${t}.${deliveryId}.${attempt}.${method}.${path}.`),
    body,
  ]);

  // 4. HMAC-SHA256, hex.
  const expected = crypto.createHmac("sha256", SIGNING_SECRET).update(signed).digest("hex");
  const expectedBuf = Buffer.from(expected);

  // 5. Constant-time compare against each v1; accept if any matches.
  const ok = v1s.some((v1) => {
    const got = Buffer.from(v1);
    return got.length === expectedBuf.length && crypto.timingSafeEqual(got, expectedBuf);
  });
  if (!ok) return res.status(401).send("signature mismatch");

  // 6. Dedup on Idempotency-Key BEFORE acting.
  const idemKey = req.get("Idempotency-Key");
  if (alreadyProcessed(idemKey)) return res.status(200).send("ok (duplicate)");
  markProcessed(idemKey);

  const payload = JSON.parse(body.toString("utf8")); // now safe to parse
  // ... handle payload ...
  res.status(200).send("ok");
});

app.listen(3000);

Python (Flask)

import hashlib
import hmac
import os
import time

from flask import Flask, request, abort

# The signing secret you configured for the schedule, as raw bytes.
SIGNING_SECRET = os.environ["SCHEDSTACK_SIGNING_SECRET"].encode()
TOLERANCE_SECONDS = 300

app = Flask(__name__)

# Stub: replace with a durable, atomic check (DB unique key, Redis SETNX, …).
_seen = set()
def already_processed(k): return k in _seen
def mark_processed(k): _seen.add(k)

@app.post("/webhooks/sched")
def sched_webhook():
    header = request.headers.get("Sched-Signature")
    if not header:
        abort(400)  # unsigned delivery

    # 1. Parse t and every v1.
    t = None
    v1s = []
    for part in header.split(","):
        k, _, v = part.strip().partition("=")
        if k == "t":
            t = int(v)
        elif k == "v1" and v:
            v1s.append(v)
    if t is None or not v1s:
        abort(400)

    # 2. Reject stale timestamps (replay protection).
    if abs(int(time.time()) - t) > TOLERANCE_SECONDS:
        abort(400)

    # 3. Rebuild the signed string. get_data() returns the RAW body bytes.
    body = request.get_data()
    delivery_id = request.headers["Sched-Delivery-Id"]
    attempt = request.headers["Sched-Attempt"]
    method = request.method.upper()
    path = request.path  # escaped path component, no query string
    prefix = f"{t}.{delivery_id}.{attempt}.{method}.{path}.".encode()
    signed = prefix + body

    # 4. HMAC-SHA256, hex.
    expected = hmac.new(SIGNING_SECRET, signed, hashlib.sha256).hexdigest()

    # 5. Constant-time compare against each v1; accept if any matches.
    if not any(hmac.compare_digest(v1, expected) for v1 in v1s):
        abort(401)

    # 6. Dedup on Idempotency-Key BEFORE acting.
    idem_key = request.headers["Idempotency-Key"]
    if already_processed(idem_key):
        return "ok (duplicate)", 200
    mark_processed(idem_key)

    payload = request.get_json(force=True)  # now safe to parse
    # ... handle payload ...
    return "ok", 200

FastAPI / Starlette

The logic is identical. Read the raw body with body = await request.body() inside an async def handler, take request.method and request.url.path, and read headers from request.headers. Everything else (parse, tolerance, HMAC, hmac.compare_digest) is the same.

Go (net/http)

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "io"
  "net/http"
  "os"
  "strconv"
  "strings"
  "time"
)

// The signing secret you configured for the schedule, as raw bytes.
var signingSecret = []byte(os.Getenv("SCHEDSTACK_SIGNING_SECRET"))

const toleranceSeconds = 300

// Stub: replace with a durable, atomic check (DB unique key, Redis SETNX, …).
func alreadyProcessed(k string) bool { return false }
func markProcessed(k string)         {}

func handler(w http.ResponseWriter, r *http.Request) {
  header := r.Header.Get("Sched-Signature")
  if header == "" {
    http.Error(w, "missing signature", http.StatusBadRequest) // unsigned delivery
    return
  }

  // 1. Parse t and every v1.
  var ts int64
  var haveTS bool
  var v1s []string
  for _, part := range strings.Split(header, ",") {
    k, v, found := strings.Cut(strings.TrimSpace(part), "=")
    if !found {
      continue
    }
    switch k {
    case "t":
      n, err := strconv.ParseInt(v, 10, 64)
      if err != nil {
        http.Error(w, "bad t", http.StatusBadRequest)
        return
      }
      ts, haveTS = n, true
    case "v1":
      if v != "" {
        v1s = append(v1s, v)
      }
    }
  }
  if !haveTS || len(v1s) == 0 {
    http.Error(w, "bad signature header", http.StatusBadRequest)
    return
  }

  // 2. Reject stale timestamps (replay protection).
  if d := time.Now().Unix() - ts; d > toleranceSeconds || d < -toleranceSeconds {
    http.Error(w, "timestamp out of tolerance", http.StatusBadRequest)
    return
  }

  // 3. Read the RAW body, then rebuild the signed string.
  body, err := io.ReadAll(r.Body)
  if err != nil {
    http.Error(w, "read error", http.StatusBadRequest)
    return
  }
  deliveryID := r.Header.Get("Sched-Delivery-Id")
  attempt := r.Header.Get("Sched-Attempt")
  method := strings.ToUpper(r.Method)
  path := r.URL.EscapedPath() // matches the signer exactly; no query string
  prefix := strconv.FormatInt(ts, 10) + "." + deliveryID + "." + attempt + "." + method + "." + path + "."
  signed := append([]byte(prefix), body...)

  // 4. HMAC-SHA256, hex.
  mac := hmac.New(sha256.New, signingSecret)
  mac.Write(signed)
  expected := []byte(hex.EncodeToString(mac.Sum(nil)))

  // 5. Constant-time compare against each v1; accept if any matches.
  ok := false
  for _, v1 := range v1s {
    if hmac.Equal([]byte(v1), expected) {
      ok = true
      break
    }
  }
  if !ok {
    http.Error(w, "signature mismatch", http.StatusUnauthorized)
    return
  }

  // 6. Dedup on Idempotency-Key BEFORE acting.
  idemKey := r.Header.Get("Idempotency-Key")
  if alreadyProcessed(idemKey) {
    w.WriteHeader(http.StatusOK)
    return
  }
  markProcessed(idemKey)

  // ... json.Unmarshal(body, &payload); handle ...
  w.WriteHeader(http.StatusOK)
}

func main() {
  http.HandleFunc("/webhooks/sched", handler)
  http.ListenAndServe(":3000", nil)
}

The escaped path

{path} is the URL-escaped path component of your endpoint URL — the path as it appears in the request line, with percent-encoding preserved and no query string. It defaults to / when the endpoint has no path.

For ordinary ASCII paths like /webhooks/sched, the escaped path and the decoded path are identical, so any path accessor works. If your routes contain percent-encoded or non-ASCII characters, derive the value from the raw request target so it matches the signer byte-for-byte:

• Go — r.URL.EscapedPath() matches exactly.
• Node — new URL(req.originalUrl, "http://x").pathname preserves percent-encoding.
• Python — request.path is decoded; for escaped paths read the raw request target from the WSGI environment and split on ?. The exact key is server-specific — gunicorn exposes RAW_URI, others use REQUEST_URI; under ASGI servers it may be absent, so fall back to request.path for ordinary ASCII paths (the common case).

Unsigned deliveries

If a schedule has no active signing secret, the Sched-Signature header is omitted entirely and the delivery is unsigned. (Sched-Timestamp, Sched-Delivery-Id, Sched-Attempt, and Idempotency-Key are still sent.)

Treat a missing Sched-Signature as a failure on any endpoint you expect to be signed — the examples above return 400 rather than silently trusting the request. Configure a signing secret before relying on signatures in production.

Why both signature and idempotency key

The signature proves authenticity (this request is from SchedStack and was not tampered with). The Idempotency-Key gives you exactly-once effect on top of at-least-once delivery: the same occurrence carries the same key across every retry and reclaim, so deduping on it makes redelivery a no-op. You need both. A verified-but-duplicate request is still a duplicate.

Tradeoff, stated plainly

Delivery is at-least-once, so you are responsible for dedup. Our dispatch SLO covers the time to initiate a delivery, not your endpoint’s processing — slow or failing receivers are retried, which is exactly when duplicates appear.

Next steps

• Quickstart — create your first schedule and receive a delivery.
• Introduction — the durability model and core guarantees.