Webhook-Adressen richtest du normalerweise in der Oberfläche ein, siehe Webhooks von FlowModels einrichten. Wenn du viele Umgebungen automatisch aufsetzt, kann dein Deployment das auch selbst über die Schnittstelle erledigen. Hier stehen die Endpunkte, und welcher Schlüssel wofür nötig ist.
Welcher Schlüssel?
- Anlegen, auflisten, ändern, löschen, testen und das Zustellprotokoll lesen: Schlüssel mit KI nutzen
- Secret wechseln: Schlüssel mit Schlüssel verwalten. Ein Schlüssel mit KI nutzen bekommt hier
403 insufficient_key_scope.
Alle Pfade beginnen mit https://api.flowmodels.one/v1.
Eine Adresse anlegen
curl -X POST https://api.flowmodels.one/v1/webhook_endpoints \
-H "Authorization: Bearer at_dein_schluessel" \
-H "Content-Type: application/json" \
-d '{"url": "https://portal.example.de/webhooks/flowmodels", "events": ["response.completed", "response.failed", "credit.threshold"], "description": "Kundenportal Produktion"}'
url: eine öffentlich erreichbarehttps-Adresse, höchstens 2.048 Zeichen. Wir prüfen sie beim Speichern und vor jeder Zustellung erneut.events: mindestens ein Ereignis aus dieser Liste:response.completed,response.failed,response.cancelled,response.incomplete,credit.threshold,credit.topup_failed,webhook_endpoint.deactivated,webhook.testdescription: optional, höchstens 255 Zeichen
Die Antwort enthält die id der Adresse und im Feld secret das Signatur-Secret. Das Secret steht nur in dieser einen Antwort. Speichere es sofort in deiner Geheimnisverwaltung. Wie du damit Zustellungen prüfst, steht in Webhook-Signatur prüfen: Beispielcode für PHP, Node.js und Python.
Je Team sind höchstens 10 Adressen möglich. Die elfte wird mit HTTP 400 abgelehnt.
Auflisten, ändern, löschen
| Aufgabe | Aufruf |
|---|---|
| alle Adressen | GET /webhook_endpoints |
| eine Adresse | GET /webhook_endpoints/{id} |
| ändern | PATCH /webhook_endpoints/{id} |
| löschen | DELETE /webhook_endpoints/{id} |
Die Listen sind seitenweise mit limit und after aufgebaut. Ein Secret geben diese Aufrufe nie zurück.
Mit PATCH änderst du url, events, description und is_active. Mit "is_active": false pausierst du eine Adresse, mit true nimmst du sie wieder in Betrieb, zum Beispiel nachdem wir sie wegen wiederholter Fehler abgeschaltet haben.
DELETE entfernt die Adresse zusammen mit ihrem Zustellprotokoll. Eine unbekannte oder fremde ID beantworten wir mit 404 webhook_endpoint_not_found.
Testen und Zustellungen prüfen
POST /webhook_endpoints/{id}/test stellt eine Zustellung vom Typ webhook.test in die Warteschlange. Die Antwort kommt sofort mit status: "pending", die eigentliche Zustellung folgt kurz danach.
Ob sie angekommen ist, siehst du mit GET /webhook_endpoints/{id}/deliveries. Jeder Eintrag nennt event_type, status, die Zahl der attempts, den http_status deines Servers, failure_kind und die Zeitpunkte. Mit ?status= filterst du nach:
pending: wartet auf die Zustellungdelivered: dein Server hat mit 2xx geantwortetfailed: der letzte Versuch ist gescheitert, ein weiterer folgtexhausted: alle Versuche sind gescheitert
Das Secret wechseln
curl -X POST https://api.flowmodels.one/v1/webhook_endpoints/{id}/rotate_secret \
-H "Authorization: Bearer at_dein_verwaltungsschluessel"
Die Antwort enthält das neue secret, wieder nur dieses eine Mal, und secondary_secret_expires_at. Bis zu diesem Zeitpunkt, also 24 Stunden lang, signieren wir jede Zustellung mit beiden Secrets. Der Header webhook-signature enthält dann zwei Werte. So kannst du das neue Secret in Ruhe auf allen Servern ausrollen, ohne dass eine Zustellung verloren geht.
Gut zu wissen
- Das Ereignis
webhook_endpoint.deactivatedgeht an alle anderen aktiven Adressen deines Teams, nie an die gerade abgeschaltete. Lege also am besten eine zweite Adresse an, wenn du über Abschaltungen informiert werden willst. - Für Hintergrundaufträge kannst du beim Start die
ideiner Adresse alswebhook_endpoint_idmitgeben, siehe Lange Anfragen im Hintergrund.