Inhalt zusammenfassen mit:
Ein Conversation-Ended Webhook macht aus einer beendeten WhatsApp- oder Webchat-Konversation einen verarbeitbaren Geschäftsprozess. Statt Transkripte manuell zu kopieren, kann ein Unternehmen strukturierte Ergebnisse direkt an CRM, Helpdesk, Data Warehouse oder eine Automatisierung übergeben. Entscheidend ist jedoch nicht nur, dass ein Webhook gesendet wird. Im Enterprise-Betrieb muss die Verarbeitung auch bei Timeouts, doppelten Events, Medienanhängen und mehrtägigen Chats zuverlässig bleiben.
Famulor liefert nach dem Ende einer Chat-Konversation den vollständigen Verlauf, extrahierte Variablen, Eingangsvariablen, Kunden- und Senderdaten sowie Zeitstempel. Bei WhatsApp können zusätzlich Bilder, Audio, Videos und Dokumente als Anhänge enthalten sein. Der folgende Blueprint zeigt, wie Teams daraus eine belastbare Integrationsstrecke bauen.
Was der Conversation-Ended Webhook abdeckt
Der Webhook ist für asynchrone Verarbeitung nach einer Unterhaltung gedacht. Er eignet sich zum Beispiel dafür, einen Lead anzulegen, ein Ticket zu aktualisieren, eine Zusammenfassung zu archivieren oder ein Folge-Workflow zu starten. Er ist nicht mit einer Mid-call Action zu verwechseln: Mid-call Actions greifen während eines laufenden Gesprächs auf Systeme zu; der Conversation-Ended Webhook übergibt das Ergebnis nach dem Ende einer WhatsApp- oder Web-Widget-Konversation.
| Datenbereich | Wichtige Felder | Typischer Zweck |
|---|---|---|
| Identität | conversation_id, assistant_id, type | Korrelation, Routing und Deduplizierung |
| Ergebnis | extracted_variables, input_variables | CRM-Felder, Qualifizierung und Workflow-Entscheidungen |
| Verlauf | transcript, formatted_transcript | Nachvollziehbarkeit, Qualitätssicherung und Support-Kontext |
| Zeit | timestamp, timestamp_unix, created_at, ended_at | Reihenfolge, SLA-Messung und Dauer |
| Medien | attachments mit Typ, URL und Dateiname | Dokumenten- oder Bildverarbeitung |
| Kanal | customer_phone, customer_name, sender | Kontaktzuordnung und kanalabhängige Logik |
Die robuste Zielarchitektur: schnell bestätigen, später verarbeiten
Ein Webhook-Endpunkt sollte möglichst wenig synchron erledigen. Er nimmt das Event entgegen, prüft die Grundform, speichert den unveränderten Payload und legt einen Job in einer Queue ab. Erst danach laufen CRM-Updates, Medienanalyse, Benachrichtigungen oder umfangreiche Transformationen. So kann der Endpunkt schnell mit einem 2xx-Status antworten und vermeidet unnötige Wiederholungen.
- Event annehmen: Payload-Größe begrenzen, JSON parsen und Pflichtfelder wie
conversation_idsowiestatusprüfen. - Unverändert speichern: Den Raw Payload mit Empfangszeit und internem Delivery-Status ablegen. Das schafft eine prüfbare Quelle für spätere Replays.
- Deduplizieren: Für Conversation-Ended Events eignet sich
conversation_idals fachlicher Schlüssel. Die Datenbank sollte denselben Abschluss nicht zweimal als neuen Vorgang verbuchen. - Asynchron verarbeiten: Ein Worker übernimmt Feldmapping, CRM-Upsert, Ticket-Erstellung, Analytics und Benachrichtigungen.
- Ergebnis protokollieren: Zielsystem, HTTP- oder API-Ergebnis, Versuchszahl und Fehlerklasse erfassen. Dadurch wird aus „Webhook gesendet“ ein messbarer Prozess.
Retries sind ein Sicherheitsnetz, keine Verarbeitungslogik
Wenn der konfigurierte Endpunkt fehlschlägt oder keinen 2xx-Status liefert, wiederholt Famulor die Zustellung nach 30, 60 und 120 Sekunden. Nach drei fehlgeschlagenen Wiederholungen wird die Zustellung als fehlgeschlagen markiert. Diese Staffelung fängt kurze Netzwerk- oder Plattformstörungen ab. Sie ersetzt aber weder eine Queue noch Idempotenz im Zielsystem.
Der wichtigste Grundsatz lautet: Eine erneute Zustellung darf denselben Geschäftsvorgang nicht doppelt auslösen. Ein CRM-Upsert ist daher sicherer als ein blindes „Create“. Für Folgeaktionen kann eine separate Idempotency-Tabelle beispielsweise conversation_id + action_name speichern. Dann lässt sich eindeutig erkennen, ob bereits ein Ticket erstellt, eine E-Mail versendet oder ein Deal aktualisiert wurde.
Replays und Audit-Trails für den operativen Alltag
Famulor zeigt das Ergebnis einer Webhook-Zustellung inklusive Status und Antwort an. Teams können den Webhook für eine Konversation erneut senden; in Listen stehen außerdem Bulk-Aktionen für Neubewertung und erneute Zustellung zur Verfügung. Das ist besonders wertvoll, wenn ein CRM vorübergehend nicht erreichbar war oder ein Feldmapping korrigiert wurde.
Ein kontrollierter Replay-Prozess braucht drei Regeln:
- Replay ist idempotent: Das Zielsystem aktualisiert denselben Datensatz, statt Duplikate anzulegen.
- Original und Verarbeitung bleiben getrennt: Der unveränderte Payload wird nicht überschrieben; Transformationen erhalten eine Versionsnummer.
- Jeder Versuch ist sichtbar: Zeitpunkt, Auslöser, Version und Ergebnis gehören in das Betriebsprotokoll.
Die vollständige Feldbeschreibung und das Retry-Verhalten stehen in der Famulor-Dokumentation zum Conversation-Ended Webhook.
Welche Systeme sollte Voice AI verbinden?
Wähle deine vorhandenen Tools und erhalte einen schnellen Integrationspfad.
Famulor
Voice AI
Ausgewählte Integrationen: 4
Medienanhänge sicher verarbeiten
WhatsApp-Konversationen können Bilder, Audio, Videos und Dokumente enthalten. Der Webhook liefert dafür ein attachments-Array mit Typ, URL und Dateiname. Behandeln Sie diese URLs nicht wie vertrauenswürdige interne Dateien. Ein sauberer Medienpfad lädt Inhalte serverseitig, setzt Größen- und Typgrenzen, prüft Dateien und speichert sie nur so lange wie für den definierten Zweck erforderlich.
- Dateityp anhand des tatsächlichen Inhalts prüfen, nicht nur anhand der Endung.
- Download- und Verarbeitungszeit begrenzen.
- Personenbezogene Inhalte nach Rollen und Mandanten trennen.
- Aufbewahrung, Löschung und Zugriff protokollieren.
- Analysefehler in eine Dead-Letter Queue verschieben, ohne das gesamte Event zu verlieren.
Für ausgehende WhatsApp-Nachrichten ergänzt der Read-Receipts Webhook den Prozess um Zustände wie sent, delivered, read und failed. Dieser Webhook ist mit HMAC-SHA256 signiert. Die Signatur muss über dem unveränderten Request Body geprüft werden; Statusupdates sollten anhand von Nachrichten-ID und Status dedupliziert werden.
Von technischen Events zu belastbaren Unternehmenskennzahlen
Ein Webhook-Projekt ist erst dann produktionsreif, wenn sein Zustand sichtbar ist. Für ein Operations-Dashboard reichen zunächst wenige Kennzahlen:
- Anteil der beim ersten Versuch akzeptierten Events
- End-to-End-Zeit vom Gesprächsende bis zum erfolgreichen Zielsystem-Update
- Anzahl und Alter offener oder fehlgeschlagener Jobs
- Replay-Quote und häufigste Fehlerklasse
- Anteil der Events mit Anhängen sowie Fehlerquote der Medienverarbeitung
- Quote fehlender Pflichtfelder im CRM-Mapping
Diese Metriken zeigen nicht nur technische Probleme. Ein plötzlicher Anstieg fehlender Qualifizierungsfelder kann auf einen ungeeigneten Prompt oder eine geänderte Gesprächslogik hinweisen. Webhook-Observability verbindet damit Plattformbetrieb und Conversational-AI-Qualität.
Implementierungscheckliste
- Conversation-Ended Webhook am Assistenten aktivieren und einen HTTPS-Endpunkt hinterlegen.
- Fachliches Schema für CRM, Helpdesk oder Data Warehouse festlegen.
- Raw Event Store und eindeutigen Idempotency-Key einrichten.
- Queue, Worker, Retry- und Dead-Letter-Strategie definieren.
- Medienpfad mit Typ-, Größen-, Malware- und Aufbewahrungsregeln absichern.
- Testfälle für WhatsApp, Web Widget, mehrtägige Chats, menschliche Übernahme und Anhänge ausführen.
- Fehlgeschlagene Zustellung simulieren und Replay ohne Duplikate nachweisen.
- Alarmierung und Verantwortlichkeit für festhängende Events dokumentieren.
Wer noch keine Automationsarchitektur festgelegt hat, kann mit der Famulor Automation Platform beginnen oder über API und eigene Queue-Systeme integrieren. Für WhatsApp-spezifische Abläufe bietet die Famulor WhatsApp AI den passenden Kanalbaustein.
FAQ
Worin unterscheidet sich ein Conversation-Ended Webhook von einem Post-Call Webhook?
Der Conversation-Ended Webhook bezieht sich auf Chat-Konversationen über WhatsApp oder Web Widget. Telefonanrufe verwenden den Post-Call Webhook. Beide können Folgeprozesse starten, aber Payload und Kanalmetadaten unterscheiden sich.
Kann ein Event mehrfach ankommen?
Ja. Wiederholungen sind bei Webhooks grundsätzlich möglich, insbesondere nach einem Timeout oder Nicht-2xx-Status. Der Empfänger sollte deshalb jede Verarbeitung idempotent gestalten.
Welche ID sollte für die Deduplizierung verwendet werden?
Für den Abschluss einer Chat-Konversation ist conversation_id der zentrale fachliche Schlüssel. Für einzelne Folgeaktionen empfiehlt sich eine Kombination aus Konversations-ID und Aktionsname.
Sollte das CRM direkt im HTTP-Handler aktualisiert werden?
Für kleine Tests ist das möglich, im Produktionsbetrieb ist eine Queue robuster. Der Handler kann schnell bestätigen, während ein Worker externe Systeme mit eigener Fehlerbehandlung aktualisiert.
Wie startet ein Team am besten?
Beginnen Sie mit einem einzigen Zielsystem und einem klaren Outcome, zum Beispiel „qualifizierten Lead per Upsert im CRM speichern“. Ergänzen Sie erst danach Medienanalyse, Benachrichtigungen und weitere Automationen.
