Was ist ein Webhook in Clickfone?
Ein Webhook ist eine Brücke zwischen deinem Agenten und einem externen System. Wenn der Agent während eines Anrufs eine bestimmte Aktion ausführen soll — Termin buchen, Lead anlegen, E-Mail senden — schickt er einen HTTP-Request an die URL, die du definiert hast.
Der Agent entscheidet während des Gesprächs selbst, wann ein Webhook ausgeführt wird, basierend auf den Tools, die du ihm zur Verfügung stellst. Du beschreibst nur, was das Tool macht — er entscheidet, wann.
Easy Mode vs. Advanced Mode
Im Easy Mode wählst du vorgefertigte Bausteine wie „Termine prüfen" oder „E-Mail senden". Die Webhook-Konfiguration läuft im Hintergrund. Reicht für 80 % der Anwendungsfälle.
Im Advanced Mode definierst du eigene Webhooks komplett — URL, Methode, Headers, Parameter. Brauchst du für individuelle CRMs, eigene APIs oder feingranulare Datenmappings.
Webhook anlegen — URL, Methode, Headers
Im Tools-Tab → Advanced Mode → „+ Neues Tool". Vier Pflichtfelder:
1. Interner Name
Wie du das Tool später wiedererkennst — z. B. create_calendar_event. Keine Leerzeichen, nur Buchstaben und Unterstriche.
2. Wann das Tool genutzt werden soll
Eine kurze Beschreibung — der Agent liest sie und entscheidet danach, wann er das Tool ausführt. Beispiel: Wird ausgeführt, wenn ein Anrufer einen Termin buchen möchte.
3. API-Adresse (URL)
Die Endpoint-URL des Ziels. Beispiel für Google Calendar: https://www.googleapis.com/calendar/v3/calendars/primary/events
4. HTTP-Methode
POST für Erstellen, GET für Abfragen, PUT / PATCH für Updates, DELETE für Löschen. Im Zweifel: API-Doku des Ziels.
Parameter-Mapping
Parameter sind die Daten, die der Agent aus dem Gespräch extrahiert und an das externe System weitergibt. Beispiel für eine Termin-Buchung:
| Parameter | Typ | Beschreibung | Pflicht |
|---|---|---|---|
| start_time | string (ISO 8601) | Beginn des Termins | Ja |
| duration_minutes | integer | Dauer in Minuten | Ja |
| caller_name | string | Name des Anrufers | Ja |
| caller_phone | string | Telefonnummer | Optional |
| notes | string | Freitext-Anmerkung | Optional |
Wichtig: Die Beschreibung pro Parameter ist nicht für dich — sie ist für den Agenten. Schreibe sie so, dass das LLM versteht, was es extrahieren soll.
Authentifizierung
Die meisten APIs verlangen Authentifizierung. Drei gängige Muster:
Bearer-Token (am häufigsten)
API-Key im Header
Basic Auth
Testen und Debuggen
Jeder Webhook-Aufruf wird im Webhook-Log protokolliert. Du findest ihn im Tools-Tab unter dem Tool → „Letzte Aufrufe".
Für jeden Aufruf siehst du:
- Vollständigen Request (URL, Method, Headers, Body)
- HTTP-Status-Code der Antwort
- Response-Body
- Dauer in ms
Wenn ein Aufruf fehlschlägt, prüfe in dieser Reihenfolge:
- 401/403 → Authentifizierung. Header falsch oder Token abgelaufen.
- 404 → URL falsch. Oft fehlt ein / am Ende.
- 422 → Pflichtparameter fehlen oder falscher Datentyp.
- 500/502 → Problem beim Zielsystem, nicht bei Clickfone.
Detaillierte Fehleranalyse: Schritt-für-Schritt — Webhook gibt Fehler zurück.
Fertige Vorlagen nutzen
Du musst nicht jedes Webhook von Grund auf bauen. Wir haben getestete Konfigurationen für die häufigsten Integrationen:
- HubSpot Lead anlegen — Kontakt im HubSpot CRM erstellen
- Google Calendar Termin — Termin im Kalender mit Erinnerung
- SendGrid E-Mail — Transactional E-Mail mit Template
- Pipedrive Deal — Deal in der Pipeline anlegen
Alle Vorlagen mit fertigen Header- und Parameter-Definitionen findest du in der Vorlagen-Bibliothek. Kopieren, API-Key einsetzen, fertig.
War dieser Artikel hilfreich?
Frage nicht beantwortet?
Schreib uns direkt — wir antworten innerhalb von 24 Stunden an Werktagen.
E-Mail an info@clickfone.de