Wir melden uns, wenn etwas fertig ist.
FlowModels ruft deine Adresse auf, wenn ein Hintergrundlauf endet, eine Schwelle erreicht ist oder ein Ziel ausfällt. Jede Zustellung ist signiert, fehlgeschlagene werden wiederholt.
Fünf Versuche, dann ist Schluss.
Antwortet dein Server nicht innerhalb von 10 Sekunden oder nicht mit einem 2xx-Status, versucht FlowModels es nach festen Abständen erneut. Zu jedem Abstand kommen bis zu 30 Sekunden Zufall, damit nicht alle Wiederholungen gleichzeitig eintreffen.
- Versuch 1 sofort
- Versuch 2 +60 s nach etwa 1 Minute
- Versuch 3 +300 s nach etwa 6 Minuten
- Versuch 4 +900 s nach etwa 21 Minuten
- Versuch 5 +3.600 s nach etwa 81 Minuten
Nach dem fünften erfolglosen Versuch steht die Zustellung auf exhausted. Scheitern fünf Zustellungen hintereinander, schaltet FlowModels das Ziel ab, sagt dir per Mail Bescheid und schickt webhook_endpoint.deactivated an deine anderen Ziele.
Jeden Versuch siehst du im Zustellungsverlauf: GET /v1/webhook_endpoints/{uuid}/deliveries, mit den Status pending, delivered, failed und exhausted.
Acht Ereignisse.
Beim Anlegen eines Ziels wählst du mindestens eines aus. Je Team sind bis zu zehn Ziele möglich.
| Ereignis | Wird ausgelöst |
|---|---|
response.completed |
Ein Hintergrundlauf ist fertig |
response.failed |
Ein Hintergrundlauf ist fehlgeschlagen |
response.cancelled |
Ein Hintergrundlauf wurde abgebrochen |
response.incomplete |
Ein Hintergrundlauf endete unvollständig |
credit.threshold |
Eine deiner Warnschwellen wurde erreicht |
credit.topup_failed |
Eine automatische Aufladung ist fehlgeschlagen |
webhook_endpoint.deactivated |
Ein Ziel wurde nach wiederholten Fehlschlägen abgeschaltet |
webhook.test |
Du hast die Testzustellung ausgelöst |
Bei den vier response.*-Ereignissen stehen nur die ID und der Status im Body. Das Ergebnis holst du mit GET /v1/responses/{id} ab, ein Inhalt verlässt FlowModels nicht über den Webhook.
Prüfe jede Signatur.
Die drei Header folgen dem Schema von Standard Webhooks. Die Signatur ist ein HMAC-SHA256 über {webhook-id}.{webhook-timestamp}.{Body}, Base64-kodiert mit dem Präfix v1,. Das Geheimnis verwendest du so, wie du es bekommen hast: als Text, nicht Base64-dekodiert.
POST /flowmodels/events HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: 018f1234-5678-7abc-9def-0123456789ab
webhook-timestamp: 1767225600
webhook-signature: v1,<Base64 von HMAC-SHA256>
{
"id": "018f1234-5678-7abc-9def-0123456789ab",
"type": "response.completed",
"created_at": "2026-11-09T10:15:00+00:00",
"data": {
"id": "018f9abc-1234-7def-8abc-0123456789ab",
"status": "completed"
}
}
import base64, hashlib, hmac, time
def is_valid(body: bytes, headers, secret: str) -> bool:
webhook_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
# Reject replays: five minutes in either direction.
if abs(time.time() - int(timestamp)) > 300:
return False
signed = f"{webhook_id}.{timestamp}.".encode() + body
digest = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(digest).decode()
# During a rotation the header carries two signatures.
return any(hmac.compare_digest(expected, candidate)
for candidate in headers["webhook-signature"].split(" "))
Ein Ziel anlegen und testen.
Das Geheimnis steht nur in der Antwort auf das Anlegen. POST /v1/webhook_endpoints/{uuid}/test legt eine echte Testzustellung in die Warteschlange und antwortet mit 202.
curl https://api.flowmodels.one/v1/webhook_endpoints \
-H "Authorization: Bearer $FLOWMODELS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/flowmodels/events",
"events": ["response.completed", "credit.threshold"],
"description": "Produktion"
}'
Geheimnis wechseln, ohne Ausfall.
POST /v1/webhook_endpoints/{uuid}/rotate_secret liefert ein neues Geheimnis, einmalig und nur mit einem Schlüssel für die Verwaltung. 24 Stunden lang signiert FlowModels mit dem alten und dem neuen Geheimnis, im Header stehen dann zwei Werte. So stellst du um, ohne eine Zustellung zu verlieren.
Nur öffentliche HTTPS-Ziele.
Die Adresse muss mit https:// beginnen und höchstens 2.048 Zeichen lang sein. Ein Ziel darf nicht auf ein internes Netz zeigen: FlowModels prüft das beim Speichern und noch einmal vor jedem Versuch, verbindet sich fest mit der geprüften Adresse und folgt keinen Weiterleitungen.