Webhooks

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

const TOLERANCE_SECONDS = 300;

export function verifyVerifyMeSignature({ secret, timestamp, signatureHeader, rawBody }) {
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > TOLERANCE_SECONDS) return false;

  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex")
  );
  // The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
  return String(signatureHeader || "").split(",").some((part) => {
    const [version, sig] = part.trim().split("=");
    if (version !== "v1" || !sig) return false;
    const given = Buffer.from(sig);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

const app = express();

// IMPORTANT: use the raw body. If a JSON parser runs first, the bytes change and verification fails.
app.post("/hooks/verifyme", express.raw({ type: "application/json", limit: "256kb" }), async (req, res) => {
  const ok = verifyVerifyMeSignature({
    secret: process.env.VERIFYME_WEBHOOK_SECRET,
    timestamp: req.get("X-VerifyMe-Timestamp"),
    signatureHeader: req.get("X-VerifyMe-Signature"),
    rawBody: req.body,
  });
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  if (await alreadyProcessed(event.eventId)) return res.sendStatus(200);   // dedupe: delivery is at-least-once

  await queue.add("verifyme-event", event);        // do the real work asynchronously
  await markProcessed(event.eventId);
  res.sendStatus(200);                             // any 2xx acknowledges within 8 seconds
});

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

TOLERANCE_SECONDS = 300


def verify_signature(secret: str, timestamp: str, signature_header: str, raw_body: bytes) -> bool:
    try:
        ts = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    # The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
    for part in (signature_header or "").split(","):
        version, _, sig = part.strip().partition("=")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False


app = Flask(__name__)


@app.post("/hooks/verifyme")
def verifyme_webhook():
    raw = request.get_data()                      # raw bytes, before any JSON parsing
    if not verify_signature(
        os.environ["VERIFYME_WEBHOOK_SECRET"],
        request.headers.get("X-VerifyMe-Timestamp", ""),
        request.headers.get("X-VerifyMe-Signature", ""),
        raw,
    ):
        abort(401)

    event = request.get_json(force=True)
    if already_processed(event["eventId"]):       # dedupe: delivery is at-least-once
        return "", 200
    enqueue("verifyme-event", event)              # do the real work asynchronously
    mark_processed(event["eventId"])
    return "", 200                                # any 2xx acknowledges within 8 seconds

using System.Security.Cryptography;
using System.Text;

public static class VerifyMeSignature
{
    public static bool Verify(string secret, string? timestamp, string? signatureHeader,
                              byte[] rawBody, int toleranceSeconds = 300)
    {
        if (!long.TryParse(timestamp, out var ts)) return false;
        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > toleranceSeconds) return false;

        var payload = Encoding.UTF8.GetBytes(timestamp + ".").Concat(rawBody).ToArray();
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var expected = Encoding.UTF8.GetBytes(Convert.ToHexString(hmac.ComputeHash(payload)).ToLowerInvariant());

        // The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
        foreach (var part in (signatureHeader ?? "").Split(','))
        {
            var kv = part.Trim().Split('=', 2);
            if (kv.Length == 2 && kv[0] == "v1" &&
                CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(kv[1]), expected))
                return true;
        }
        return false;
    }
}

// ASP.NET Core minimal API
app.MapPost("/hooks/verifyme", async (HttpRequest req, IConfiguration cfg, IEventStore store) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);                          // raw bytes, before any JSON binding
    var raw = ms.ToArray();

    if (!VerifyMeSignature.Verify(cfg["VerifyMe:WebhookSecret"]!,
            req.Headers["X-VerifyMe-Timestamp"], req.Headers["X-VerifyMe-Signature"], raw))
        return Results.Unauthorized();

    using var doc = System.Text.Json.JsonDocument.Parse(raw);
    var eventId = doc.RootElement.GetProperty("eventId").GetString()!;
    if (await store.SeenAsync(eventId)) return Results.Ok();   // dedupe: delivery is at-least-once

    await store.EnqueueAsync(eventId, raw);                    // do the real work asynchronously
    return Results.Ok();                                       // any 2xx acknowledges within 8 seconds
});

import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class VerifyMeSignature {
  private VerifyMeSignature() {}

  public static boolean verify(String secret, String timestamp, String signatureHeader,
                               byte[] rawBody, long toleranceSeconds) {
    long ts;
    try { ts = Long.parseLong(timestamp); } catch (NumberFormatException e) { return false; }
    if (Math.abs(Instant.now().getEpochSecond() - ts) > toleranceSeconds) return false;
    if (signatureHeader == null) return false;

    try {
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
      mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
      byte[] expected = HexFormat.of().formatHex(mac.doFinal(rawBody)).getBytes(StandardCharsets.UTF_8);

      // The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
      for (String part : signatureHeader.split(",")) {
        String[] kv = part.trim().split("=", 2);
        if (kv.length == 2 && kv[0].equals("v1")
            && MessageDigest.isEqual(kv[1].getBytes(StandardCharsets.UTF_8), expected)) return true;
      }
    } catch (GeneralSecurityException e) {
      return false;
    }
    return false;
  }
}

// Spring Boot controller
@PostMapping("/hooks/verifyme")
public ResponseEntity<Void> verifyme(
    @RequestBody byte[] rawBody,                                   // raw bytes, not a bound DTO
    @RequestHeader(value = "X-VerifyMe-Timestamp", required = false) String timestamp,
    @RequestHeader(value = "X-VerifyMe-Signature", required = false) String signature) throws IOException {
  if (!VerifyMeSignature.verify(secret, timestamp, signature, rawBody, 300))
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();

  JsonNode event = objectMapper.readTree(rawBody);
  String eventId = event.get("eventId").asText();
  if (store.seen(eventId)) return ResponseEntity.ok().build();     // dedupe: delivery is at-least-once
  store.enqueue(eventId, rawBody);                                 // do the real work asynchronously
  return ResponseEntity.ok().build();                              // any 2xx acknowledges within 8 seconds
}

<?php
const VERIFYME_TOLERANCE_SECONDS = 300;

function verifyMeSignature(string $secret, string $timestamp, string $signatureHeader, string $rawBody): bool
{
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > VERIFYME_TOLERANCE_SECONDS) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    // The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
    foreach (explode(',', $signatureHeader) as $part) {
        [$version, $sig] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $sig)) {
            return true;
        }
    }
    return false;
}

// hooks/verifyme.php
$raw = file_get_contents('php://input');                 // raw bytes, before any JSON decoding
$ok = verifyMeSignature(
    getenv('VERIFYME_WEBHOOK_SECRET'),
    $_SERVER['HTTP_X_VERIFYME_TIMESTAMP'] ?? '',
    $_SERVER['HTTP_X_VERIFYME_SIGNATURE'] ?? '',
    $raw
);
if (!$ok) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
if (alreadyProcessed($event['eventId'])) {               // dedupe: delivery is at-least-once
    http_response_code(200);
    exit;
}
enqueue('verifyme-event', $event);                       // do the real work asynchronously
http_response_code(200);                                 // any 2xx acknowledges within 8 seconds

package main

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

const toleranceSeconds = 300

func verifySignature(secret, timestamp, header string, body []byte) bool {
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > toleranceSeconds {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(body)
	expected := []byte(hex.EncodeToString(mac.Sum(nil)))

	// The header can carry two signatures while a secret is being rotated: "v1=<hex>,v1=<hex>"
	for _, part := range strings.Split(header, ",") {
		kv := strings.SplitN(strings.TrimSpace(part), "=", 2)
		if len(kv) == 2 && kv[0] == "v1" && hmac.Equal([]byte(kv[1]), expected) {
			return true
		}
	}
	return false
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 256<<10)) // raw bytes, before JSON decoding
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}
	if !verifySignature(os.Getenv("VERIFYME_WEBHOOK_SECRET"),
		r.Header.Get("X-VerifyMe-Timestamp"), r.Header.Get("X-VerifyMe-Signature"), body) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}
	var event struct {
		EventID   string `json:"eventId"`
		EventType string `json:"eventType"`
	}
	if err := json.Unmarshal(body, &event); err != nil {
		http.Error(w, "bad json", http.StatusBadRequest)
		return
	}
	if alreadyProcessed(event.EventID) { // dedupe: delivery is at-least-once
		w.WriteHeader(http.StatusOK)
		return
	}
	enqueue(event.EventID, body) // do the real work asynchronously
	w.WriteHeader(http.StatusOK) // any 2xx acknowledges within 8 seconds
}