Jeder Webhook von FlowModels ist signiert. Dein Server sollte diese Signatur prüfen, bevor er eine Zustellung verarbeitet. Nur so weißt du, dass die Nachricht wirklich von uns kommt und unterwegs nicht verändert wurde. Hier findest du das Verfahren und fertigen Prüfcode für PHP, Node.js und Python.
Was mitgeschickt wird
Jede Zustellung ist ein POST mit JSON und diesen drei Headern:
webhook-id: die eindeutige Kennung der Zustellung. Bei Wiederholungen bleibt sie gleich.webhook-timestamp: der Zeitpunkt der Signatur in Unix-Sekundenwebhook-signature: die Signatur im Formatv1,<Base64>
Der Inhalt hat immer die Felder id, type, created_at und data. Bei den Ereignissen response.* enthält data nur die id und den status des Auftrags. Das Ergebnis holst du anschließend selbst mit GET /v1/responses/{id}.
So wird signiert
- Wir bilden den Text
{webhook-id}.{webhook-timestamp}.{Inhalt}, mit Punkten dazwischen und dem unveränderten Inhalt der Anfrage. - Daraus berechnen wir einen HMAC mit SHA-256. Als Schlüssel dient dein Signatur-Secret, und zwar genau der Text, den wir dir angezeigt haben.
- Das Ergebnis wird Base64-kodiert und mit
v1,davor inwebhook-signaturegeschrieben.
Wichtig: Verwende das Secret als normalen Text. Es ist eine zufällige Zeichenfolge aus 48 Zeichen und beginnt nicht mit whsec_. Fertige Bibliotheken für „Standard Webhooks“ entfernen ein Präfix wie whsec_, dekodieren den Rest als Base64 und berechnen damit den HMAC. Mit dem Secret von FlowModels ergibt das eine andere Signatur, und die Prüfung schlägt fehl. Nimm deshalb den kurzen Prüfcode unten.
Prüfe außerdem den Zeitstempel. Wir empfehlen, Zustellungen abzulehnen, deren Zeitstempel mehr als fünf Minuten von deiner Serverzeit abweicht. Das schützt vor dem erneuten Einspielen abgefangener Nachrichten.
PHP
<?php
$secret = getenv('FLOWMODELS_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$header = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';
if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(400);
exit;
}
$expected = 'v1,' . base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $secret, true));
$valid = false;
foreach (preg_split('/\s+/', trim($header)) as $candidate) {
if (hash_equals($expected, $candidate)) {
$valid = true;
break;
}
}
if (! $valid) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// Ereignis verarbeiten, zum Beispiel anhand von $event['type']
http_response_code(204);
Node.js mit Express
import crypto from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.FLOWMODELS_WEBHOOK_SECRET;
app.post("/webhooks/flowmodels", express.raw({ type: "application/json" }), (req, res) => {
const id = req.get("webhook-id") ?? "";
const timestamp = req.get("webhook-timestamp") ?? "";
const header = req.get("webhook-signature") ?? "";
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.sendStatus(400);
}
const expected = "v1," + crypto.createHmac("sha256", secret)
.update(`${id}.${timestamp}.`)
.update(req.body) // roher Inhalt als Buffer
.digest("base64");
const valid = header.split(/\s+/).some((candidate) =>
candidate.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(candidate), Buffer.from(expected)));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString("utf8"));
// Ereignis verarbeiten
res.sendStatus(204);
});
Python mit Flask
import base64, hashlib, hmac, os, time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["FLOWMODELS_WEBHOOK_SECRET"].encode()
@app.post("/webhooks/flowmodels")
def flowmodels_webhook():
msg_id = request.headers.get("webhook-id", "")
timestamp = request.headers.get("webhook-timestamp", "")
header = request.headers.get("webhook-signature", "")
body = request.get_data() # rohe Bytes
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
abort(400)
mac = hmac.new(SECRET, f"{msg_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(mac).decode()
if not any(hmac.compare_digest(expected, c) for c in header.split()):
abort(401)
event = request.get_json()
# Ereignis verarbeiten
return "", 204
Die häufigsten Fehler
- Der Inhalt wurde vor der Prüfung verändert. Viele Frameworks lesen das JSON automatisch ein. Prüfe immer den rohen Inhalt, so wie er angekommen ist. Schon ein anderes Leerzeichen oder umkodierte Umlaute ergeben eine andere Signatur.
- Das Secret wurde als Base64 dekodiert. Siehe oben, nimm es als Text.
- Nur ein Wert in
webhook-signaturegeprüft. Nach Secret rotieren enthält der Header 24 Stunden lang zwei Werte, getrennt durch ein Leerzeichen, je einen für das alte und das neue Secret. Der Code oben prüft alle und akzeptiert beim ersten Treffer. - Serverzeit falsch. Geht deine Serveruhr deutlich falsch, scheitert die Zeitprüfung. Synchronisiere sie per NTP.
Was dein Server antworten muss
- Antworte mit einem Statuscode 2xx, dann gilt die Zustellung als erfolgreich. Den Inhalt deiner Antwort lesen wir nicht.
- Antworte innerhalb von 10 Sekunden. Erledige aufwendige Arbeit danach, zum Beispiel über eine Warteschlange.
- Weiterleitungen (3xx) folgen wir nicht, sie gelten als Fehler.
Klappt eine Zustellung nicht, versuchen wir es erneut, nach etwa 1, 5, 15 und 60 Minuten, insgesamt bis zu fünfmal. Weil eine Zustellung dadurch mehrfach ankommen kann, verarbeite jede webhook-id nur einmal. Nach fünf endgültig gescheiterten Zustellungen in Folge schalten wir die Adresse ab, siehe Webhooks von FlowModels einrichten.
Die Prüfung testen
Öffne im Dashboard den Punkt Webhooks und wähle bei deiner Adresse Testzustellung senden. Wir schicken dann ein Ereignis webhook.test. Im Zustellprotokoll siehst du, mit welchem HTTP-Code dein Server geantwortet hat.


Hast du das Secret verloren, erzeugst du mit Secret rotieren ein neues. Wir zeigen jedes Secret nur einmal an.