FlowModels

Webhooks per API anlegen, testen und das Secret wechseln

Veröffentlicht am 11. November 2026

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 erreichbare https-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.test
  • description: 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 Zustellung
  • delivered: dein Server hat mit 2xx geantwortet
  • failed: der letzte Versuch ist gescheitert, ein weiterer folgt
  • exhausted: 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.deactivated geht 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 id einer Adresse als webhook_endpoint_id mitgeben, siehe Lange Anfragen im Hintergrund.

War dieser Artikel hilfreich?

Zurück zu Webhooks, Endnutzer & MCP