Signaturen prüfen
Prüfe unveränderte Request-Bytes, lehne veraltete Requests ab und dedupliziere anhand der signierten Ereignis-ID.
Calberry sendet Webhook-Signature: t=<Unixsekunden>,v1=<hex> und Webhook-Id. Die Signatur ist ein HMAC-SHA256 über die exakten Bytes von <t>.<unveränderter Request-Body>.
Verwende das ausgegebene Secret vollständig als UTF-8-String einschließlich whsec_. Nicht Base64-dekodieren. Lies die ursprünglichen Bodybytes vor dem JSON-Parsing; erneutes Serialisieren verändert die signierte Eingabe.
Dasselbe Protokoll signiert Flow-Webhooks, einschließlich synthetischer Tests, Retry und Replay. Der folgende Verifier funktioniert auch mit deren unverändertem Body.
Ablauf im Empfänger
- Begrenze die Bodygröße und lies die unveränderten Bytes.
- Prüfe das Headerformat und das konfigurierte Zeitfenster, sowohl für zu alte als auch zu weit in der Zukunft liegende Zeitstempel.
- Berechne den HMAC und vergleiche konstantzeitlich.
- Parse erst danach JSON und validiere die Ereignishülle.
- Dedupliziere über
event_idaus dem signierten Body. Falls duWebhook-Idnutzt, prüfe die Übereinstimmung. - Verhindere echte Geschäftsaktionen für
data.test=true. Speichere normale Ereignisse dauerhaft, bevor du sie mit 2xx bestätigst.
Verwende keinen unsignierten Header allein zur Deduplizierung. Der Signaturzeitpunkt des Zustellversuchs ist vom ursprünglichen Ereigniszeitpunkt created_at getrennt.
Node.js-Verifier
Die Funktion braucht keine externen Abhängigkeiten. rawBody ist ein Buffer/Uint8Array, nowSeconds die tatsächliche aktuelle Unixzeit und die nicht negative Toleranz kommt aus deiner Empfängerkonfiguration. true bestätigt nur Signatur und Zeitfenster, nicht die fachliche Gültigkeit der Nutzdaten.
import { createHmac, timingSafeEqual } from "node:crypto";
function verifyWebhookSignature(rawBody, header, secret, nowSeconds, toleranceSeconds) {
if (typeof header !== "string" || typeof secret !== "string" || !secret) return false;
const match = /^t=(0|[1-9]\d*),v1=([0-9a-f]{64})$/.exec(header);
if (!match) return false;
const timestamp = Number(match[1]);
if (!Number.isSafeInteger(timestamp) ||
!Number.isSafeInteger(nowSeconds) || nowSeconds < 0 ||
!Number.isSafeInteger(toleranceSeconds) || toleranceSeconds < 0 ||
Math.abs(nowSeconds - timestamp) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}Testvektor
Der absichtlich minimale synthetische Body prüft das Signaturprotokoll und ist kein vollständiges fachliches Ereignis. Verwende rawBody exakt wie gezeigt, ohne abschließenden Zeilenumbruch. Das Secret ist ein öffentliches Beispiel.
{
"secret": "whsec_example_for_documentation_only",
"nowSeconds": 1791892800,
"toleranceSeconds": 300,
"rawBody": "{\"event_id\":\"ev_test\",\"type\":\"booking.created\",\"created_at\":\"2026-10-13T12:00:00.000Z\",\"data\":{\"schema_version\":1,\"consent\":false}}",
"header": "t=1791892800,v1=ef3a74f0492fd65c0a1e75a7845016368f0a31072bcd45fe568251c39b2e1bf1"
}Der Aufruf verifyWebhookSignature(Buffer.from(vector.rawBody, 'utf8'), vector.header, vector.secret, vector.nowSeconds, vector.toleranceSeconds) ergibt true. Ein geänderter Body, ein angehängter Zeilenumbruch, ein anderes Secret oder eine Zeit außerhalb des Beispiel-Zeitfensters ergeben false. Im echten Handler verwendest du Math.floor(Date.now() / 1000) statt der festen Beispielzeit.
Rotation, Retry und Replay
Wiederholungen behalten Body und Ereignis-ID, bekommen aber einen neuen Zeitstempel und eine neue Signatur. Das Zeitfenster allein verhindert keine doppelten Wirkungen; speichere verarbeitete Ereignis-IDs dauerhaft.
Beim Rotieren wird das aktive Secret sofort ersetzt. Bereits laufende Versuche können noch das vorherige Secret verwenden. Akzeptiere deshalb vorübergehend beide. Secrets bleiben in serverseitiger Konfiguration und gehören weder in Logs noch in Browser-Code.
Make und Zapier können Flow-Webhooks direkt ohne Signaturprüfung empfangen. Ein gewöhnlicher Empfangsschritt setzt dieses Protokoll nicht automatisch um; halte seine URL vertraulich. Benötigst du geprüften Empfang und bietet dein No-Code-Werkzeug keinen Zugriff auf unveränderte Bytes und Header, schalte einen prüfenden Empfänger davor und leite nur geprüfte Ereignisse weiter.