Webhooks

# Shell (for a quick check, not a handler): recompute the signature over a saved raw body.
# $TIMESTAMP is the X-Webhook-Timestamp header; body.json holds the bytes exactly as received.
printf '%s.' "$TIMESTAMP" | cat - body.json \
  | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" \
  | sed 's/^.* /sha256=/'
# Compare the output with the X-Webhook-Signature header.

// Node.js: verify X-Webhook-Signature over the RAW body (use express.raw(), not express.json()).
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhookSignature(secret, timestamp, rawBody, header, toleranceSeconds = 300) {
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    return false; // too old, or from the future: a replay
  }

  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");

  return a.length === b.length && timingSafeEqual(a, b); // constant time
}

// Express example
// app.post("/hooks/messaging", express.raw({ type: "application/json" }), (req, res) => {
//   const ok = verifyWebhookSignature(
//     process.env.WEBHOOK_SECRET,
//     req.header("X-Webhook-Timestamp"),
//     req.body.toString("utf8"),
//     req.header("X-Webhook-Signature"),
//   );
//   if (!ok) return res.sendStatus(401);
//   const event = JSON.parse(req.body.toString("utf8"));
//   // Dedupe on event.id (also in X-Webhook-ID), queue the work, answer fast.
//   res.sendStatus(200);
// });

# Python: verify X-Webhook-Signature over the RAW body (request.get_data(), not request.json).
import hashlib
import hmac
import time


def verify_webhook_signature(secret: str, timestamp: str, raw_body: bytes, header: str, tolerance_seconds: int = 300) -> bool:
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False  # too old, or from the future: a replay

    signed = timestamp.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    return hmac.compare_digest(expected, header or "")  # constant time


# Flask example
# @app.post("/hooks/messaging")
# def hook():
#     ok = verify_webhook_signature(
#         os.environ["WEBHOOK_SECRET"],
#         request.headers.get("X-Webhook-Timestamp", ""),
#         request.get_data(),
#         request.headers.get("X-Webhook-Signature", ""),
#     )
#     if not ok:
#         return "", 401
#     event = request.get_json()
#     # Dedupe on event["id"] (also in X-Webhook-ID), queue the work, answer fast.
#     return "", 200

<?php
// Verify X-Webhook-Signature. Use the RAW request body - never a re-encoded one.
function verifyWebhookSignature(string $secret, string $timestamp, string $rawBody, string $header, int $toleranceSeconds = 300): bool
{
    if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $toleranceSeconds) {
        return false; // too old, or from the future: a replay
    }

    $expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);

    return hash_equals($expected, $header); // constant time
}

// In a Laravel/Symfony/plain PHP handler:
$rawBody = file_get_contents('php://input');
$ok = verifyWebhookSignature(
    getenv('WEBHOOK_SECRET'),
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '',
    $rawBody,
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
);

if (! $ok) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// Dedupe on $event['id'] (also in X-Webhook-ID), then queue the work and answer 200 fast.
http_response_code(200);

// Java 17+: verify X-Webhook-Signature over the RAW body bytes.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

public final class WebhookSignature {
    public static boolean verify(String secret, String timestamp, byte[] rawBody, String header, long toleranceSeconds) throws Exception {
        if (!timestamp.matches("\\d+") || Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > toleranceSeconds) {
            return false; // too old, or from the future: a replay
        }

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
        mac.update(rawBody);

        String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal());

        return MessageDigest.isEqual( // constant time
            expected.getBytes(StandardCharsets.UTF_8),
            (header == null ? "" : header).getBytes(StandardCharsets.UTF_8)
        );
    }
}

// In a servlet / Spring handler: read request.getInputStream() fully into rawBody
// BEFORE any JSON binding, call verify(...), answer 401 when false, then dedupe
// on the event id (X-Webhook-ID), queue the work and answer 200.

// C# (.NET 6+): verify X-Webhook-Signature over the RAW body bytes.
using System;
using System.Security.Cryptography;
using System.Text;

public static class WebhookSignature
{
    public static bool Verify(string secret, string timestamp, byte[] rawBody, string? header, long toleranceSeconds = 300)
    {
        if (!long.TryParse(timestamp, out var ts) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > toleranceSeconds)
        {
            return false; // too old, or from the future: a replay
        }

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var prefix = Encoding.UTF8.GetBytes(timestamp + ".");
        var signed = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, signed, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, signed, prefix.Length, rawBody.Length);

        var expected = "sha256=" + Convert.ToHexString(hmac.ComputeHash(signed)).ToLowerInvariant();

        return CryptographicOperations.FixedTimeEquals( // constant time
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(header ?? string.Empty));
    }
}

// ASP.NET Core: enable buffering and read Request.Body fully into rawBody BEFORE
// model binding, call Verify(...), return 401 when false, then dedupe on the
// event id (X-Webhook-ID), queue the work and return 200.

// Go: verify X-Webhook-Signature over the RAW body bytes.
package webhooks

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

func VerifyWebhookSignature(secret, timestamp string, rawBody []byte, header string, tolerance time.Duration) bool {
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	if d := time.Since(time.Unix(ts, 0)); d > tolerance || d < -tolerance {
		return false // too old, or from the future: a replay
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(expected), []byte(header)) // constant time
}

// In an http.Handler: rawBody, _ := io.ReadAll(r.Body) before any JSON decoding,
// then VerifyWebhookSignature(secret, r.Header.Get("X-Webhook-Timestamp"), rawBody,
// r.Header.Get("X-Webhook-Signature"), 5*time.Minute); 401 when false; dedupe on
// X-Webhook-ID, queue the work, answer 200.