Webhook Signing

#!/usr/bin/env bash
# Example: verify a webhook from the command line. In production, do this in
# your application code — not in a shell script.

SECRET="$WEBHOOK_SECRET"        # whsec_...
TIMESTAMP="$1"                  # value of X-Webhook-Timestamp
SIG_HEADER="$2"                 # full X-Webhook-Signature, e.g. v1=abc,v1=def
BODY="$(cat)"                   # raw body piped on stdin

NOW=$(date +%s)
AGE=$(( NOW - TIMESTAMP ))
if [ "$AGE" -gt 300 ] || [ "$AGE" -lt -300 ]; then
  echo "reject: stale timestamp ($AGE seconds)" >&2
  exit 1
fi

EXPECTED=$(printf '%s.%s' "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex \
  | awk '{print $2}')

# The header may carry more than one signature during a rotation window.
# Split on commas, strip the v1= prefix from each, and accept if any matches.
# openssl offers no constant-time compare; for non-production shells this is
# acceptable — do the comparison in your application code where it matters.
MATCH=0
IFS=',' read -ra ENTRIES <<< "$SIG_HEADER"
for entry in "${ENTRIES[@]}"; do
  if [ "$EXPECTED" = "${entry#v1=}" ]; then
    MATCH=1
    break
  fi
done

if [ "$MATCH" = "1" ]; then
  echo "ok"
else
  echo "reject: signature mismatch" >&2
  exit 1
fi

// Node 18+. Express example — mount express.raw() on the webhook route so
// req.body is a Buffer, not a parsed object.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WEBHOOK_SECRET; // whsec_...

app.post(
  "/webhooks/anton",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.header("X-Webhook-Timestamp");
    const signatureHeader = req.header("X-Webhook-Signature") || "";
    // One or more comma-separated v1= entries (two during a rotation window).
    const signatures = signatureHeader
      .split(",")
      .map((s) => s.trim().replace(/^v1=/, ""))
      .filter(Boolean);

    if (!timestamp || signatures.length === 0) {
      return res.status(400).send("missing signature headers");
    }

    const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
    if (ageSeconds > 300) {
      return res.status(400).send("stale timestamp");
    }

    const body = req.body; // Buffer — the raw bytes Anton signed
    const signedString = `${timestamp}.${body.toString("utf8")}`;
    const expected = crypto
      .createHmac("sha256", SECRET)
      .update(signedString)
      .digest("hex");
    const expectedBuf = Buffer.from(expected, "hex");

    // Accept if the computed signature matches ANY entry (constant-time).
    const valid = signatures.some((sig) => {
      const actualBuf = Buffer.from(sig, "hex");
      return (
        actualBuf.length === expectedBuf.length &&
        crypto.timingSafeEqual(expectedBuf, actualBuf)
      );
    });
    if (!valid) {
      return res.status(400).send("invalid signature");
    }

    const event = JSON.parse(body.toString("utf8"));
    // ... handle event ...
    res.status(200).send();
  },
);

<?php
// Symfony / Laravel: read the raw body via $request->getContent() or
// file_get_contents("php://input"). Don't use $_POST — it will be empty
// for JSON payloads and wrong for form-encoded ones.

$secret = getenv("WEBHOOK_SECRET"); // whsec_...
$body = file_get_contents("php://input");
$timestamp = $_SERVER["HTTP_X_WEBHOOK_TIMESTAMP"] ?? "";
$signatureHeader = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? "";

if ($timestamp === "" || $signatureHeader === "") {
    http_response_code(400);
    exit("missing signature headers");
}

if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit("stale timestamp");
}

$expected = hash_hmac("sha256", $timestamp . "." . $body, $secret);

// The header may carry more than one v1= entry during a rotation window.
// Accept if any matches (constant-time via hash_equals).
$valid = false;
foreach (explode(",", $signatureHeader) as $entry) {
    $sig = preg_replace("/^v1=/", "", trim($entry));
    if (hash_equals($expected, $sig)) {
        $valid = true;
        break;
    }
}

if (!$valid) {
    http_response_code(400);
    exit("invalid signature");
}

$event = json_decode($body, true);
// ... handle event ...
http_response_code(200);

package main

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

var secret = []byte(os.Getenv("WEBHOOK_SECRET")) // whsec_...

func handleWebhook(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "read body", http.StatusBadRequest)
		return
	}

	timestamp := r.Header.Get("X-Webhook-Timestamp")
	signatureHeader := r.Header.Get("X-Webhook-Signature")
	if timestamp == "" || signatureHeader == "" {
		http.Error(w, "missing signature headers", http.StatusBadRequest)
		return
	}

	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		http.Error(w, "bad timestamp", http.StatusBadRequest)
		return
	}
	if diff := time.Now().Unix() - ts; diff > 300 || diff < -300 {
		http.Error(w, "stale timestamp", http.StatusBadRequest)
		return
	}

	mac := hmac.New(sha256.New, secret)
	fmt.Fprintf(mac, "%d.%s", ts, body)
	expectedBytes := mac.Sum(nil)

	// The header may carry more than one v1= entry during a rotation window.
	// Accept if the computed signature matches any of them (constant-time).
	valid := false
	for _, entry := range strings.Split(signatureHeader, ",") {
		sig := strings.TrimPrefix(strings.TrimSpace(entry), "v1=")
		actualBytes, err := hex.DecodeString(sig)
		if err == nil && hmac.Equal(expectedBytes, actualBytes) {
			valid = true
			break
		}
	}
	if !valid {
		http.Error(w, "invalid signature", http.StatusBadRequest)
		return
	}

	var event struct {
		ID        string          `json:"id"`
		Type      string          `json:"type"`
		CreatedAt string          `json:"created_at"`
		Data      json.RawMessage `json:"data"`
	}
	if err := json.Unmarshal(body, &event); err != nil {
		http.Error(w, "bad json", http.StatusBadRequest)
		return
	}
	// ... handle event ...
	w.WriteHeader(http.StatusOK)
}