Webhooks
Mit Webhooks empfängt Ihr System nach jedem abgeschlossenen Anruf automatisch die Gesprächsdaten — Transkript, Zusammenfassung, Dauer und mehr. Der Webhook-Empfang ist in den meisten Anwendungsfällen der direkten API-Abfrage vorzuziehen, weil er keine Polling-Logik erfordert.
Was Sie erreichen werden
- Einen Webhook-Workflow im Dashboard einrichten
- Authentifizierung und Retry-Verhalten konfigurieren
- Die Payload-Struktur und verfügbare Variablen verstehen
- Häufige Einrichtungsprobleme selbst beheben
Voraussetzungen
- Ein erreichbarer HTTPS-Endpunkt auf Ihrem Server, der POST-Anfragen entgegennimmt
- Einen API-Schlüssel (für die Konfiguration per API)
Schritt 1: Webhook im Dashboard einrichten
- Melden Sie sich bei app.dalvon.ai an
- Navigieren Sie in der Seitenleiste zu Postprocessing
- Klicken Sie auf Neuer Workflow
- Wählen Sie den Typ Webhook
- Tragen Sie Ihre Ziel-URL ein
- Wählen Sie eine Authentifizierungsmethode (empfohlen: Bearer Token oder API Key)
- Klicken Sie auf Speichern
Alternativ können Sie den Webhook per API erstellen:
curl -X POST "https://api.dalvon.ai/postprocessing/" \
-H "Authorization: Bearer IHR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM-Integration",
"description": "Sendet Anrufdaten an unser CRM",
"config": {
"type": "webhook",
"url": "https://ihre-domain.de/webhook/calls",
"method": "POST",
"auth_type": "bearer",
"auth_config": {
"token": "ihr-geheimer-token"
}
}
}'
Schritt 2: Konfiguration anpassen
Basis-Einstellungen
| Feld | Typ | Beschreibung |
|---|---|---|
url | string | Ziel-URL des Webhooks (erforderlich, muss HTTPS sein) |
method | string | HTTP-Methode: GET, POST, PUT, PATCH, DELETE (Default: POST) |
headers | object | Zusätzliche HTTP-Header als Schlüssel-Wert-Paare |
body_template | string | Body-Template mit Variablen (optional; leer = Standard-Payload) |
query_params | object | Zusätzliche URL-Query-Parameter |
Authentifizierung
auth_type | Beschreibung | Erforderliche auth_config-Felder |
|---|---|---|
none | Keine Authentifizierung | — |
bearer | Bearer Token im Authorization-Header | { "token": "..." } |
basic | HTTP Basic Auth | { "username": "...", "password": "..." } |
api_key | API Key in einem konfigurierbaren Header | { "header": "X-Api-Key", "key": "..." } |
Retry-Einstellungen
| Feld | Typ | Default | Beschreibung |
|---|---|---|---|
retry_count | int | 3 | Wiederholungsversuche bei Fehler (0–10) |
retry_delay_seconds | int | 5 | Wartezeit zwischen Versuchen in Sekunden |
timeout_seconds | int | 30 | Timeout pro Anfrage in Sekunden (max. 300) |
success_status_codes | array | [200, 201, 202, 204] | HTTP-Codes, die als Erfolg gewertet werden |
So funktioniert es: Antwortet Ihr Endpunkt mit einem nicht in
success_status_codesenthaltenen Code, wiederholt die Plattform die Anfrage nachretry_delay_secondsSekunden — bis zuretry_count-mal. Antworten Sie daher so früh wie möglich mit200und verarbeiten Sie die Daten asynchron weiter.
Webhook-Payload
Der Standard-Payload, den Ihr Endpunkt empfängt:
{
"event": "call.completed",
"timestamp": "2024-01-15T14:30:00Z",
"call": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"agent_id": "660e8400-e29b-41d4-a716-446655440001",
"phone_number": "+491234567890",
"direction": "outbound",
"status": "completed",
"duration_seconds": 180,
"started_at": "2024-01-15T14:25:00Z",
"ended_at": "2024-01-15T14:28:00Z",
"transcript": "Kunde: Guten Tag...",
"summary": "Kunde hat Termin für nächste Woche vereinbart."
}
}
Verfügbare Variablen im body_template
Möchten Sie nur bestimmte Felder übermitteln, nutzen Sie ein body_template mit Platzhaltern. Die folgende Tabelle zeigt die wichtigsten verfügbaren Variablen:
| Variable | Beschreibung | Verfügbarkeit |
|---|---|---|
{{call.id}} | Eindeutige Anruf-ID | Immer |
{{call.phone_number}} | Angerufene / anrufende Nummer | Immer |
{{call.direction}} | inbound oder outbound | Immer |
{{call.duration}} | Gesprächsdauer in Sekunden | Nach Abschluss |
{{call.started_at}} | Startzeitpunkt (ISO 8601) | Immer |
{{call.ended_at}} | Endzeitpunkt (ISO 8601) | Nach Abschluss |
{{call.transcript}} | Vollständiges Transkript | Nach Abschluss |
{{call.summary}} | KI-generierte Zusammenfassung | Nach Abschluss |
{{call.topic}} | Erkanntes Gesprächsthema | Nach Abschluss |
{{call.recipient_number}} | Nummer des Weiterleitungsziels | Bei Weiterleitung |
{{contact.first_name}} | Vorname des erkannten Kontakts | Wenn Kontakt gefunden |
{{contact.last_name}} | Nachname des erkannten Kontakts | Wenn Kontakt gefunden |
{{contact.email}} | E-Mail des Kontakts | Wenn Kontakt gefunden |
Variablen, die im konkreten Anruf nicht befüllt sind, werden durch einen leeren String ersetzt. Verschachtelte JSON-Objekte im body_template sind unterstützt.
Konfigurationsbeispiele
Einfacher POST ohne Authentifizierung
{
"name": "Einfache Benachrichtigung",
"config": {
"type": "webhook",
"url": "https://ihre-domain.de/webhook/calls",
"method": "POST"
}
}
Mit Bearer-Token und erhöhtem Timeout
{
"name": "CRM-Update",
"config": {
"type": "webhook",
"url": "https://api.ihr-crm.de/calls",
"method": "POST",
"auth_type": "bearer",
"auth_config": {
"token": "sk_live_xxx"
},
"retry_count": 5,
"timeout_seconds": 60
}
}
Mit eigenen Headern und API-Key
{
"name": "Partner-API",
"config": {
"type": "webhook",
"url": "https://partner.example.com/webhook",
"method": "POST",
"headers": {
"X-Partner-ID": "12345"
},
"auth_type": "api_key",
"auth_config": {
"header": "X-API-Key",
"key": "ihre-api-key"
}
}
}
Sicherheitsempfehlungen
- Verwenden Sie ausschließlich HTTPS-URLs
- Schützen Sie den Endpunkt mit Authentifizierung (Bearer Token oder API Key)
- Validieren Sie eingehende Anfragen serverseitig (z.B. anhand des Token-Headers)
- Antworten Sie sofort mit
200und verarbeiten Sie die Daten asynchron
Weitere Postprocessing-Typen
Neben Webhooks können Anrufdaten auch per E-Mail, SMS oder WhatsApp zugestellt werden. Konfiguration und Empfänger richten Sie über den Agenten-Editor unter Nachverarbeitung ein.
| Typ | Beschreibung |
|---|---|
email | Zusammenfassung und Transkript per E-Mail |
sms | Kurze SMS-Benachrichtigung |
whatsapp | WhatsApp-Nachricht mit Gesprächsdetails |
Fehlerbehebung
Webhook wird nicht aufgerufen
- Prüfen Sie, ob der Postprocessing-Workflow auf Aktiv gesetzt ist
- Stellen Sie sicher, dass Ihre URL von außen erreichbar ist (öffentliche IP oder Domain)
- Prüfen Sie den Ausführungsverlauf im Dashboard unter Postprocessing → Verlauf
Timeouts
- Erhöhen Sie
timeout_seconds(max. 300) - Lassen Sie Ihren Endpunkt sofort mit
200antworten und verarbeiten Sie die Daten asynchron - Prüfen Sie die Performance Ihres Endpunkts unter Last
Authentifizierungsfehler
- Gleichen Sie Token und Header-Namen ab
- Testen Sie den Endpunkt manuell mit
curlund denselben Headern
404 direkt nach dem Webhook
Wenn Sie nach Empfang des Webhooks sofort GET /calls/<id> aufrufen und einen 404 erhalten, kann dies an einer kurzen Verarbeitungslatenz liegen. Warten Sie einige Sekunden, bevor Sie den Anruf per API abrufen, oder lesen Sie die Details direkt aus dem Webhook-Payload. Mehr dazu unter API-Fehler beheben.
Nächste Schritte
- API-Fehler beheben - 404, 5xx und andere Fehler systematisch lösen
- API-Einführung - Grundlagen der REST API und Authentifizierung
- MCP mit Claude Desktop - Agenten per natürlicher Sprache steuern