Agent-Webhooks

Der Tab Webhook eines Agents erzeugt eindeutige URLs, an die externe Systeme POSTen und mit dem Agent chatten können — nichts in der UI ist beteiligt. Greif dazu, wenn etwas außerhalb von Tale den Agent antworten lassen soll: ein Slack-Bot, ein Formular-Handler, ein geplanter Job.

Diese Seite deckt nur die Webhook-Oberfläche pro Agent ab. Für eingehende Trigger, die einen Workflow statt eines Agents starten, siehe Workflows → Trigger; für die volle Entwickler-Oberfläche siehe Entwickeln → API-Referenz.

Einen Webhook erstellen

Öffne den Agent, wechsle zu Webhook und klicke auf Webhook erstellen. Der Dialog zeigt die neue URL genau einmal — sichere sie, denn das in der URL eingebettete Token wirkt als Zugangsnachweis. Es gibt keinen separaten API-Schlüssel und keine Kopfzeile: wer die URL hält, kann mit dem Agent chatten, also behandle sie wie ein Geheimnis.

Aufrufen

POSTe einen JSON-Body mit einem message-Feld; die Antwort ist die Antwort des Agents:

curl -X POST https://tale.yourcompany.com/api/agents/wh/<token> \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Drei Felder formen den Aufruf:

• stream — ergänze "stream": true, und die Antwort kommt als Server-Sent Events statt als eine JSON-Antwort.
• threadId — ohne startet jeder POST eine frische Konversation; übergib die Thread-Id aus einer früheren Antwort, um eine mit intaktem Kontext fortzusetzen.
• Dateien — schick multipart/form-data mit einem message-Feld und einem oder mehreren file-Feldern, um Uploads an die Nachricht zu hängen.

Die Aktion Verwendungsbeispiele jeder Zeile öffnet fertige Beispiele für all das, ausgefüllt mit der echten URL der Zeile.

Der OpenAI-kompatible Endpunkt

Ein an die Webhook-URL angehängtes /chat/completions stellt einen ChatCompletion-Endpunkt im OpenAI-Stil bereit, sodass fertige OpenAI-Clients auf einen Agent zeigen können: nutze die Webhook-URL als Basis-URL, einen beliebigen nicht-leeren Wert als API-Schlüssel und eine Modell-Id aus der Modell-Liste des Agents (unbekannte Werte fallen auf den Standard zurück). Datei-Uploads unterstützt nur die Basis-Webhook-URL, nicht dieser Unterpfad.

Verwalten und widerrufen

Die Tabelle zeigt die URL jedes Webhooks, einen Aktiv-Schalter und den Zeitpunkt der letzten Auslösung. Einen Webhook abzuschalten pausiert ihn, ohne die URL zu verlieren; ihn zu löschen ist der Widerruf — jedes System, das die URL noch nutzt, verliert den Zugriff, also stell den Ersatz-Webhook bereit, bevor du den alten stilllegst.

Wo das hingehört

Webhooks sind die leichte Integrations-Oberfläche pro Agent — richtig, wenn die Integration „dieser eine Agent beantwortet diese eine Sache“ ist. Für reichere Abläufe mit Schritten und Genehmigungen modelliere die Arbeit als Automatisierung und richte den Aufrufer auf den Webhook-Trigger der Automatisierung — Automatisierung per Webhook auslösen geht diese Form von Anfang bis Ende durch.