Dokumentation

Webhooks

Senden Sie signierte Echtzeit-Ereignisse an externe Dienste.

Webhooks senden signierte Benachrichtigungen, wenn sich Leads, Formulare, Unterhaltungen oder Eskalationen ändern. Sie erfordern einen Hobby-Plan oder höher mit aktiver Abrechnung.

Einen Endpunkt konfigurieren

Öffnen Sie bei einem Agenten Einstellungen → Webhooks, wählen Sie ein oder mehrere Ereignisse aus, geben Sie einen öffentlichen HTTPS-Endpunkt ein und erstellen Sie die Abonnements. Agentkit verwaltet ein gemeinsames Signaturgeheimnis für alle Ereigniszeilen desselben Endpunkts. Kontoinhaber können es über die Endpunktkarte anzeigen oder rotieren lassen.

Unterstützte Ereignisnamen sind:

  • lead_created
  • form_submission (veralteter Lead-Alias)
  • custom_form_submitted
  • conversation_started
  • conversation_ended
  • escalation_created

conversation_ended wird nach 30 Minuten ohne Nachricht ausgelöst. Sein Transkript ist eine unveränderliche Momentaufnahme von höchstens 200 Nachrichten, wobei jede Nachricht auf 2.000 Zeichen begrenzt ist. Unterhaltungen, die nur im Playground stattfanden oder keine Nutzernachricht enthalten, werden nicht ausgeliefert. Die Transkriptanalyse ist derzeit null.

Umschlag

Jedes Ereignis verwendet denselben stabilen Umschlag:

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Verwenden Sie eventId als Idempotenzschlüssel. Die Zustellung erfolgt mindestens einmal, eine Reihenfolge wird nicht garantiert. Dieselbe Ereignis-ID, derselbe Zeitstempel des Vorfalls und dieselben JSON-Bytes werden bei Wiederholungen erneut verwendet.

Signaturen überprüfen

Zustellungen enthalten:

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Lesen Sie den Request-Body als rohen UTF-8-Text. Parsen Sie t und v1, berechnen Sie HMAC-SHA256 mit dem Endpunkt-Geheimnis über die exakten Bytes von t + "." + rawBody und vergleichen Sie die Digests mit einer zeitkonstanten Funktion. Parsen und reserialisieren Sie das JSON vor der Überprüfung nicht. Lehnen Sie veraltete Zeitstempel gemäß Ihrer Replay-Richtlinie ab.

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Zuverlässigkeit und Ergebnisse

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Eine Nicht-2xx-Antwort, ein Timeout oder ein Netzwerkfehler wird nach der ersten Anfrage fünfmal mit QStash-Backoff wiederholt (in der Regel sechs Versuche insgesamt). Die Einstellungsseite zeigt die letzten 20 endgültigen Ergebnisse.

Ein erschöpftes Ereignis erhöht den Fehler-Zähler nur einmal, unabhängig von der Anzahl der Versuche oder doppelter Callbacks. Ein Abonnement wird erst automatisch deaktiviert, nachdem mindestens 10 aufeinanderfolgende erschöpfte Ereignisse über mindestens sieben Tage aufgetreten sind. Inhaber erhalten eine wiederholbare Benachrichtigung und können das Abonnement nach der Behebung wieder aktivieren. Ein erfolgreiches Ereignis setzt den Zähler zurück.

Endpunkt-URLs müssen HTTP oder HTTPS verwenden, müssen öffentlich erreichbar sein und dürfen nicht auf localhost, private/link-lokale IP-Bereiche oder Cloud-Metadaten-Endpunkte verweisen. In der Produktion ist HTTPS erforderlich. Bei der Zustellung löst Agentkit den Hostnamen einmal auf, verlangt, dass jede aufgelöste Adresse öffentlich ist, und bindet die Verbindung an diese Adressen – DNS-Rebinding kann eine Zustellung daher nicht auf eine interne Adresse umleiten.

Zeitplanaktivierung

Der Code für den Sweep inaktiver Unterhaltungen wird deaktiviert ausgeliefert. Ein Operator kann nach dem Deployment pnpm --filter chatbots setup:idle-conversation-webhooks prüfen und ausführen. Der Befehl legt den 15-minütigen QStash-Zeitplan an; das Mergen von Code erstellt oder aktiviert ihn nicht.

Nächste Schritte