Verify the signature

# Flask — pip install compense-sdk-python flask
import os
import queue
import threading

from flask import Flask, request
from compense_gateway.webhooks import WebhookEvent, WebhookVerificationError, verify_webhook

app = Flask(__name__)

# The current secret and, only while you rotate, the previous one.
SECRETOS = [s for s in (os.environ.get("COMPENSE_WEBHOOK_SECRET"),
                        os.environ.get("COMPENSE_WEBHOOK_SECRET_OLD")) if s]

procesados: set[str] = set()                 # in production: your DB or Redis (with a TTL of days)
cola: "queue.Queue[WebhookEvent]" = queue.Queue()


def manejar(event: WebhookEvent) -> None:
    print(event.event, event.event_id, event.resource)   # your business logic


def trabajador() -> None:
    while True:
        manejar(cola.get())


threading.Thread(target=trabajador, daemon=True).start()


@app.post("/compense/webhooks")
def recibir():
    try:
        # request.get_data(): the raw bytes, BEFORE any parsing
        event = verify_webhook(request.get_data(), request.headers, secret=SECRETOS)
    except WebhookVerificationError:
        return "", 401                       # invalid signature or timestamp

    if event.is_test:                        # send_test: acknowledge it and don't process it
        return "", 200
    if event.event_id in procesados:         # duplicate delivery (at-least-once)
        return "", 200
    procesados.add(event.event_id)

    cola.put(event)                          # the heavy work, outside the request
    return "", 200

// Express — npm i @compense/sdk express
import express from "express";
import { verifyWebhook, WebhookVerificationError, type WebhookEvent } from "@compense/sdk/webhooks";

const app = express();

// The current secret and, only while you rotate, the previous one.
const secretos = [process.env.COMPENSE_WEBHOOK_SECRET, process.env.COMPENSE_WEBHOOK_SECRET_OLD].filter(
  (s): s is string => Boolean(s),
);
const procesados = new Set<string>(); // in production: your DB or Redis (with a TTL of days)

function manejar(event: WebhookEvent): void {
  console.log(event.event, event.eventId, event.resource); // your business logic
}

// express.raw on THIS route: req.body arrives as a Buffer with the raw bytes.
// Don't put express.json() before this route.
app.post("/compense/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  let event: WebhookEvent;
  try {
    event = verifyWebhook(req.body, req.headers, secretos);
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.sendStatus(401);
    throw err;
  }

  if (event.isTest) return res.sendStatus(200);                 // sendTest: don't process it
  if (procesados.has(event.eventId)) return res.sendStatus(200); // duplicate (at-least-once)
  procesados.add(event.eventId);

  setImmediate(() => manejar(event)); // in production: enqueue (BullMQ, SQS…)
  return res.sendStatus(200);
});

app.listen(8000, () => console.log("http://localhost:8000/compense/webhooks"));

<?php
// Laravel — composer require compense/sdk
//
// routes/api.php (without CSRF middleware):
//   Route::post('/compense/webhooks', \App\Http\Controllers\CompenseWebhookController::class);
//
// config/services.php:
//   'compense' => [
//       'webhook_secrets' => array_values(array_filter([
//           env('COMPENSE_WEBHOOK_SECRET'), env('COMPENSE_WEBHOOK_SECRET_OLD'),
//       ])),
//   ],

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Jobs\HandleCompenseEvent;
use Compense\Sdk\Webhook\Webhook;
use Compense\Sdk\Webhook\WebhookVerificationException;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

final class CompenseWebhookController
{
    public function __invoke(Request $request): JsonResponse
    {
        try {
            $event = Webhook::verify(
                $request->getContent(),          // RAW body, not $request->all() or json()
                $request->headers->all(),        // Symfony HeaderBag
                config('services.compense.webhook_secrets'),
            );
        } catch (WebhookVerificationException $e) {
            Log::warning('Compense webhook rejected', ['motivo' => $e->getMessage()]);

            return response()->json(['error' => 'invalid signature'], 401);
        }

        if ($event->isTest()) {                  // sendTest: acknowledge it and don't process it
            return response()->json(['received' => true, 'test' => true]);
        }

        // At-least-once: Cache::add only writes if the key doesn't exist (7 days covers the retries).
        if (Cache::add('compense:webhook:' . $event->eventId, true, now()->addDays(7))) {
            HandleCompenseEvent::dispatch($event->event(), $event->payload);   // to the queue
        }

        return response()->json(['received' => true]);
    }
}

// ASP.NET Core minimal API (.NET 8) — dotnet add package Compense.Sdk
//   Compense__WebhookSecrets__0=whsec_...   (current)
//   Compense__WebhookSecrets__1=whsec_...   (previous, only while you rotate)
using System.Collections.Concurrent;
using System.Threading.Channels;
using Compense.Sdk.Webhooks;

var builder = WebApplication.CreateBuilder(args);

string[] secretos = builder.Configuration.GetSection("Compense:WebhookSecrets").Get<string[]>()
    ?? Array.Empty<string>();

var procesados = new ConcurrentDictionary<string, bool>();   // in production: your DB
var cola = Channel.CreateUnbounded<WebhookEvent>();

var app = builder.Build();

// Background consumer: the heavy work doesn't block the response.
_ = Task.Run(async () =>
{
    await foreach (WebhookEvent e in cola.Reader.ReadAllAsync())
    {
        app.Logger.LogInformation("{Event} {EventId} {Resource}", e.Event, e.EventId, e.Resource);
    }
});

app.MapPost("/compense/webhooks", async (HttpRequest request) =>
{
    // The raw bytes, exactly as they arrived.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);

    WebhookEvent evt;
    try
    {
        evt = CompenseWebhooks.Verify(buffer.ToArray(), request.Headers, secretos);
    }
    catch (WebhookVerificationException ex)
    {
        app.Logger.LogWarning("Webhook rejected: {Motivo}", ex.Message);
        return Results.Unauthorized();
    }

    if (evt.IsTest) return Results.Ok();                         // SendTestAsync: don't process it
    if (!procesados.TryAdd(evt.EventId, true)) return Results.Ok(); // duplicate (at-least-once)

    await cola.Writer.WriteAsync(evt);
    return Results.Ok();
});

app.Run();

// net/http — go get github.com/Appiasoft/compense-saas-sdk-go
package main

import (
	"context"
	"log"
	"net/http"
	"os"
	"sync"
	"time"

	"github.com/Appiasoft/compense-saas-sdk-go/webhook"
)

func main() {
	// The current secret and, only while you rotate, the previous one (empty ones are ignored).
	secretos := []string{os.Getenv("COMPENSE_WEBHOOK_SECRET"), os.Getenv("COMPENSE_WEBHOOK_SECRET_OLD")}

	var mu sync.Mutex
	procesados := map[string]bool{} // in production: your DB or Redis
	cola := make(chan *webhook.Event, 1000)

	go func() { // background consumer
		for ev := range cola {
			log.Printf("%s %s %v", ev.Event(), ev.ID, ev.Resource())
		}
	}()

	// webhook.Handler verifies (401 if it fails), and responds 200 if fn returns nil
	// or 500 if it returns an error (Compense will retry the delivery).
	h := webhook.Handler(secretos, func(ctx context.Context, ev *webhook.Event) error {
		if ev.IsTest() { // SendTest: acknowledge it and don't process it
			return nil
		}
		mu.Lock()
		defer mu.Unlock()
		if procesados[ev.ID] { // duplicate (at-least-once)
			return nil
		}
		procesados[ev.ID] = true
		cola <- ev
		return nil
	})

	mux := http.NewServeMux()
	mux.Handle("/compense/webhooks", h)
	srv := &http.Server{Addr: ":8000", Handler: mux, ReadHeaderTimeout: 10 * time.Second}
	log.Fatal(srv.ListenAndServe())
}

# Simulate a signed delivery against your local receiver (useful in unit or smoke tests).
SECRET="whsec_..."                       # the same one you configured in the receiver
BODY='{"event":"test.ping","version":"1","tenant_id":"horizonte","test":true}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -i -X POST http://localhost:8000/compense/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  -H "X-Webhook-Event: test.ping" \
  -H "X-Webhook-Id: test-local-0001" \
  -H "X-Webhook-Timestamp: $(date +%s)" \
  --data-binary "$BODY"
# → 200. Change one character of $BODY without recomputing the signature → 401.

import hashlib
import hmac
import time


def firma_valida(cuerpo: bytes, cabeceras, secretos: list[str], tolerancia: int = 300) -> bool:
    ts = cabeceras.get("X-Webhook-Timestamp")
    if ts is None or abs(time.time() - int(float(ts))) > tolerancia:
        return False
    firma = (cabeceras.get("X-Webhook-Signature") or "").strip()
    if not firma.startswith("sha256="):
        return False
    recibida = firma[len("sha256="):]
    valida = False
    for secreto in secretos:                 # no short-circuit: same time with any secret
        esperada = hmac.new(secreto.encode("utf-8"), cuerpo, hashlib.sha256).hexdigest()
        valida |= hmac.compare_digest(esperada, recibida)
    return valida

import { createHmac, timingSafeEqual } from "node:crypto";

export function firmaValida(
  cuerpo: Buffer,
  cabeceras: Record<string, string | string[] | undefined>,
  secretos: string[],
  tolerancia = 300,
): boolean {
  const ts = Number(cabeceras["x-webhook-timestamp"]);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > tolerancia) return false;
  const firma = String(cabeceras["x-webhook-signature"] ?? "").trim();
  if (!firma.startsWith("sha256=")) return false;
  const recibida = Buffer.from(firma.slice("sha256=".length), "utf8");
  let valida = false;
  for (const secreto of secretos) {
    const esperada = Buffer.from(createHmac("sha256", secreto).update(cuerpo).digest("hex"), "utf8");
    valida = (esperada.length === recibida.length && timingSafeEqual(esperada, recibida)) || valida;
  }
  return valida;
}

<?php
/** @param string[] $secretos */
function firmaValida(string $cuerpo, ?string $firma, ?string $timestamp, array $secretos, int $tolerancia = 300): bool
{
    if ($timestamp === null || !is_numeric($timestamp) || abs(time() - (int) $timestamp) > $tolerancia) {
        return false;
    }
    $firma = trim((string) $firma);
    if (!str_starts_with($firma, 'sha256=')) {
        return false;
    }
    $recibida = substr($firma, strlen('sha256='));
    $valida = false;
    foreach ($secretos as $secreto) {
        $valida = hash_equals(hash_hmac('sha256', $cuerpo, $secreto), $recibida) || $valida;
    }

    return $valida;
}

$ok = firmaValida(
    (string) file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? null,
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? null,
    [(string) getenv('COMPENSE_WEBHOOK_SECRET')],
);

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

static bool FirmaValida(byte[] cuerpo, string? firma, string? timestamp, IEnumerable<string> secretos, int tolerancia = 300)
{
    if (!long.TryParse(timestamp, out long ts)
        || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > tolerancia)
    {
        return false;
    }

    firma = firma?.Trim();
    if (firma is null || !firma.StartsWith("sha256=", StringComparison.Ordinal))
    {
        return false;
    }

    byte[] recibida = Encoding.ASCII.GetBytes(firma.Substring("sha256=".Length));
    bool valida = false;
    foreach (string secreto in secretos)
    {
        byte[] hmac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secreto), cuerpo);
        byte[] esperada = Encoding.ASCII.GetBytes(Convert.ToHexString(hmac).ToLowerInvariant());
        valida |= CryptographicOperations.FixedTimeEquals(esperada, recibida);
    }

    return valida;
}

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

func firmaValida(cuerpo []byte, h http.Header, secretos []string) bool {
	ts, err := strconv.ParseInt(h.Get("X-Webhook-Timestamp"), 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return false
	}
	recibida, ok := strings.CutPrefix(strings.TrimSpace(h.Get("X-Webhook-Signature")), "sha256=")
	if !ok {
		return false
	}
	valida := false
	for _, secreto := range secretos {
		mac := hmac.New(sha256.New, []byte(secreto))
		mac.Write(cuerpo)
		esperada := hex.EncodeToString(mac.Sum(nil))
		if hmac.Equal([]byte(esperada), []byte(recibida)) {
			valida = true
		}
	}
	return valida
}

# Manually verify a saved delivery: cuerpo.json (exact bytes) and the received header.
SECRET="whsec_..."
RECIBIDA="sha256=3b0c…"                  # value of X-Webhook-Signature
ESPERADA="sha256=$(openssl dgst -sha256 -hmac "$SECRET" < cuerpo.json | sed 's/^.* //')"
[ "$ESPERADA" = "$RECIBIDA" ] && echo "valid signature" || echo "invalid signature"