Webhooks & Zustellung

Nach jedem Anruf kann Hanc.AI das Gespräch — Zusammenfassung, Gesprächsverlauf, extrahierte Felder — an Ihr eigenes System senden: ein Ticketsystem, ein CRM, ein ERP oder einen beliebigen HTTPS-Endpunkt. Diese Seite beschreibt genau, wie sich diese Zustellung verhält: was passiert, wenn Ihr Server nicht erreichbar ist, wie oft wir es erneut versuchen, was Ihre Firewall zulassen muss und wie die Anfrage aufgebaut ist.

Alle Tarife

Die Zustellung nach dem Anruf mit Wiederholungen und Zustellprotokoll ist in jedem Tarif enthalten, auch im kostenlosen.

Was gesendet wird — und wann

Eine Anfrage geht hinaus, sobald der Anruf beendet und seine Auswertung abgeschlossen ist (Zusammenfassung, Stimmung, Ihre extrahierten Felder) — in der Regel wenige Sekunden nach dem Auflegen.

Quelle	Wo Sie es einrichten
Aktion „API-Aufruf“	Agent → Folgeaktionen → Post call → API-Aufruf
Workflow-Schritt	Workflow-Builder → Tool-Schritt API-Aufruf mit Nach dem Anruf
Agent-Webhook	Feld `webhook_url` des Agenten (API-Referenz)

Anfragen, die ein Agent während des Gesprächs stellt (Live-Tools), sind hier nicht gemeint: Sie werden in genau dieser Sekunde gebraucht und nie später wiederholt.

Wenn Ihr Server nicht erreichbar ist

Es geht nichts verloren. Die Anfrage wird vor dem ersten Versuch in einer Zustellwarteschlange gespeichert und bleibt dort, bis Ihr Server sie annimmt oder der Zeitplan abgelaufen ist.

Eine Zustellung gilt als erfolgreich, wenn Ihr Endpunkt innerhalb von 30 Sekunden mit einem beliebigen 2xx-Status antwortet.
Alles andere wird wiederholt: abgelehnte Verbindung, DNS- oder TLS-Fehler, Zeitüberschreitung und jeder andere Status — 5xx, 429 und auch 4xx. Ist ein API-Schlüssel abgelaufen und Sie erneuern ihn, kommen die wartenden Anrufe von selbst an.
Jeder Versuch sendet dieselbe Anfrage mit derselben Zustell-ID.

Zeitplan der Wiederholungen

Versuch	Pause davor	Zeit seit Gesprächsende
1	— (sofort)	~0
2	1 Minute	~1 Min.
3	5 Minuten	~6 Min.
4	30 Minuten	~36 Min.
5	2 Stunden	~2 Std. 36 Min.
6	6 Stunden	~8 Std. 36 Min.
7	24 Stunden	~1 Tag 8 Std.
8	48 Stunden	~3 Tage 8 Std.

Das sind 8 Versuche über rund 3,4 Tage — genug, um auch einen Ausfall über das Wochenende zu überbrücken.

Ihr eigener Zeitplan

In einer Aktion API-Aufruf (und in einem Workflow-Schritt API-Aufruf, der nach dem Anruf läuft) können Sie den Zeitplan unter Wiederholungen bei Fehlern ersetzen:

bis zu 10 Wiederholungen,
jede Pause von 1 Minute bis 7 Tage,
entfernen Sie alle Zeilen, wird einmal gesendet — ohne Wiederholung.

Eine Aktion, die Sie nie angepasst haben, folgt dem Standardzeitplan oben.

Nach dem letzten Versuch

Die Zustellung wird als Nicht zugestellt markiert, Sie werden per E-Mail benachrichtigt — sofern Sie das nicht abgeschaltet haben —, und die Anfrage wird 30 Tage aufbewahrt. In dieser Zeit können Sie sie erneut senden — mit einem Klick im Zustellprotokoll oder einem API-Aufruf. Erneutes Senden ist auch für eine bereits erfolgreiche Zustellung möglich, etwa nach einer Wiederherstellung auf Ihrer Seite.

Unabhängig von jedem Webhook bleibt das Gespräch selbst in Ihrem Hanc.AI-Konto — Gesprächsverlauf, Zusammenfassung, Aufzeichnung und extrahierte Felder stehen unter Anrufe und über die API bereit. Ein längerer Ausfall verzögert die Übergabe an Ihr System; er löscht das Gespräch nicht.

Mindestens einmal

Die Zustellung erfolgt mindestens einmal. In seltenen Fällen — etwa wenn Ihr Server eine Anfrage verarbeitet hat, die Antwort uns aber nicht rechtzeitig erreichte — kommt derselbe Anruf zweimal an. Mit X-Hanc-Delivery-Id erkennen und überspringen Sie eine Wiederholung.

Benachrichtigung bei Fehlern

Sie müssen das Protokoll nicht beobachten: Eine Aktion kann Sie per E-Mail informieren, wenn ihre Anfrage nicht zugestellt wird. Wählen Sie unter Benachrichtigung bei Fehlern in der Aktion (oder im Workflow-Schritt):

Einstellung	Wann die E-Mail gesendet wird
Nach dem letzten Versuch (Standard)	Einmal, wenn der Zeitplan aufgebraucht ist und die Anfrage als Nicht zugestellt markiert wird
Nach jedem fehlgeschlagenen Versuch	Nach jedem fehlgeschlagenen Versuch, mit dem Zeitpunkt des nächsten — und nach dem letzten
Nicht benachrichtigen	Nie; Fehlschläge sind nur im Protokoll sichtbar

Die E-Mail nennt die Aktion und den Agenten, den Host Ihres Servers, dessen Antwort (zum Beispiel HTTP 503 oder timeout after 30s), den wievielten Versuch von wie vielen und verlinkt auf das Zustellprotokoll. Die letzte nennt zusätzlich, bis wann die Anfrage aufbewahrt wird und dass sie erneut gesendet werden kann.

Senden an legt den Empfänger fest — in der Regel, wer das empfangende System betreibt. Bleibt das Feld leer, geht die E-Mail an den Kontoinhaber. Sie wird in der Sprache des Kontos verfasst.

Damit ein Ausfall Ihr Postfach nicht überflutet, sind Benachrichtigungen pro Aktion auf 10 pro Stunde und 30 pro Tag begrenzt; die letzte vor einer Pause nennt deren Ende. Jeder Fehlschlag wird weiterhin im Protokoll festgehalten. Über eine von Hand erneut gesendete Anfrage wird nicht benachrichtigt.

Zustellprotokoll

Jeder Versuch wird protokolliert: Zeitpunkt, HTTP-Status oder Netzwerkfehler, Dauer und der Anfang der Antwort Ihres Servers.

In der App: CRM → Kommunikation → einen Eintrag vom Typ API-Aufruf öffnen. Sie sehen den Status (Zugestellt, Wird wiederholt, Nicht zugestellt), alle Versuche, den Zeitpunkt des nächsten und die Schaltfläche Erneut senden.

Über die API (Authentifizierung mit Ihrem API-Schlüssel im Header x-api-key):

Anfrage	Ergebnis
`GET /v1/webhook-deliveries`	Ihre Zustellungen, neueste zuerst. Filter: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Eine Zustellung mit allen Versuchen und dem Anfragekörper
`POST /v1/webhook-deliveries/{id}/resend`	Sendet sie jetzt erneut und liefert das Ergebnis zurück

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Ticket anlegen",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Die Header-Werte der gespeicherten Anfrage (Ihre Schlüssel) werden nie zurückgegeben.

Netzwerk & Firewall

Hanc.AI ruft Ihren Endpunkt auf — die Verbindung wird immer von unserer Seite zu Ihrer aufgebaut.


Richtung	Ausgehend von Hanc.AI → eingehend auf Ihrer Seite
Quell-IP-Adressen	`178.104.10.47` (Zustelldienst) und `128.140.65.92` (Anrufdienst, als Ausweichweg)
Protokoll	HTTPS (TLS 1.2 oder neuer). Unverschlüsseltes HTTP funktioniert, wird aber nicht empfohlen
Port	`443` oder der Port, den Ihre URL nennt
IP-Version	IPv4
Zertifikat	Muss gültig und von einer öffentlichen Zertifizierungsstelle ausgestellt sein; selbstsignierte Zertifikate werden abgelehnt
Antwortzeit	Antwort innerhalb von 30 Sekunden — am besten sofort bestätigen und im Hintergrund verarbeiten
Weiterleitungen	Werden verfolgt, höchstens 5

Whitelist: Filtert Ihre Firewall oder WAF nach Quelladresse, geben Sie die beiden Adressen oben für Ihren Webhook-Pfad frei. Eine Änderung dieser Adressen kündigen wir im Voraus an.

Nicht möglich: Adressen innerhalb eines privaten Netzes (10.x, 172.16–31.x, 192.168.x, localhost). Der Endpunkt muss aus dem Internet erreichbar sein — direkt oder über Ihren Reverse Proxy bzw. Ihr API-Gateway.

Browser: Webhooks laufen von Server zu Server. Browser-Einstellungen, Erweiterungen oder offene Ports an Arbeitsplatzrechnern sind nicht beteiligt.

Format der Anfrage

POST, PUT und PATCH tragen einen JSON-Körper (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Kunde meldet einen defekten Router und bittet um Rückruf…",
  "transcription": [
    { "speaker": "agent", "content": "Guten Tag…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hallo…",     "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Feld	Inhalt
`call_summary`	Gesprächszusammenfassung
`transcription`	Vollständiger Gesprächsverlauf, Beitrag für Beitrag, mit Zeitstempeln
`call_from`, `call_to`, `direction`	Anrufer, angerufene Nummer, eingehend oder ausgehend
`start_timestamp`, `end_timestamp`, `duration`	Unix-Zeit und Dauer in Millisekunden
`custom_analysis_data`	Ihre eigenen Felder, aus dem Gespräch extrahiert — siehe Abruf-Variablen
`collected_data`	Daten, die der Agent während des Gesprächs erfasst hat
`sentiment`, `task_achieved`	Stimmung des Gesprächs und ob sein Ziel erreicht wurde
`recording_url`	Link zur Aufzeichnung, sofern die Aufzeichnung aktiv ist
`transfer_history`	Weiterleitungen während des Anrufs

Bei GET und DELETE reisen dieselben Felder im Query-String; verschachtelte Werte wie transcription entfallen.

Header	Bedeutung
`X-Hanc-Delivery-Id`	Kennzeichnet die Zustellung. Bei jedem Versuch identisch — damit überspringen Sie Duplikate
`X-Hanc-Attempt`	Nummer des Versuchs, beginnend bei `1`
`X-Correlation-Id`	Interne Trace-ID; nennen Sie sie, wenn Sie den Support kontaktieren
`User-Agent`	`HANC-Webhooks/1.0`
Ihre Header	Alles, was Sie in der Aktion konfiguriert haben

Authentifizierung

Sie entscheiden, woran Ihr Endpunkt uns erkennt:

API-Schlüssel oder Token — fügen Sie der Aktion einen Header hinzu, z. B. Authorization: Bearer <token> oder X-API-Key: <key>. Header werden bei jedem Versuch mitgesendet.
Basic Auth — Authorization: Basic <base64(benutzer:passwort)>.
Query-Parameter — für Systeme, die den Schlüssel in der URL erwarten.
Quelladresse — nur die oben genannten IP-Adressen zulassen.

Die Verfahren lassen sich kombinieren; üblich sind ein Schlüssel plus IP-Whitelist.

Die Anfrage für Ihr System gestalten

Standardmäßig enthält die Anfrage das vollständige Gespräch (siehe Format der Anfrage). Für ein System, das seine eigene Struktur erwartet — das gilt für die meisten Ticketsysteme — beschreiben Sie diese Struktur selbst und füllen sie aus dem Anruf.

Variablen

In einer Aktion API-Aufruf nach dem Anruf und in einem Workflow-Schritt API-Aufruf nehmen URL, Header, Query-Parameter und Body Variablen in doppelten geschweiften Klammern auf. Sie werden unmittelbar vor dem Versand aus dem Anruf befüllt.

Variable	Wert
`{{call_id}}`	ID des Anrufs
`{{call_from}}`, `{{call_to}}`	Anrufer und angerufene Nummer
`{{customer_phone}}`, `{{customer_email}}`	Nummer und E-Mail der Gegenseite, unabhängig von der Richtung des Anrufs
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Beginn und Ende, ISO 8601 (UTC)
`{{call_duration}}`	Dauer in Sekunden
`{{call_summary}}`	Gesprächszusammenfassung
`{{call_transcription}}`	Vollständiger Gesprächsverlauf als Text
`{{call_sentiment}}`, `{{call_task_achieved}}`	Stimmung und ob das Ziel erreicht wurde
`{{call_recording_url}}`	Link zur Aufzeichnung
`{{agent_id}}`	ID des Agenten
Ihre Felder	Jede Abruf-Variable unter ihrem Namen, z. B. `{{customer_number}}`, `{{priority}}` — sowie jede Variable, die ein Workflow im Gespräch erfasst hat

Wissenswert:

Ein Body-Feld, das nur aus einer Variable besteht, behält deren Typ: "priority": "{{priority}}" wird als Zahl 3 gesendet, "urgent": "{{urgent}}" als true. Text um eine Variable herum macht daraus Text.
Ein Wert in der URL wird automatisch prozentkodiert (+43… wird zu %2B43…).
Eine Variable, für die der Anruf keinen Wert hat, wird leer gesendet — nie als wörtliches {{name}}.

In der App listet die Schaltfläche {x} in einem Feld die verfügbaren Variablen auf; im Body schlägt die Eingabe von {{ sie vor.

Body

Unter Body (JSON) in der Aktion schreiben Sie das JSON-Objekt, das Ihr System erwartet — beliebig tief verschachtelt:

{
  "ticket": {
    "subject": "Anruf von {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Nur Ihre Felder

Ist Nur meine Felder senden eingeschaltet, enthält die Anfrage ausschließlich Ihren Body und Ihre Query-Parameter — die Anrufdaten werden nicht angehängt. Bleibt der Schalter aus, werden Ihre Felder zusammen mit dem vollständigen Gespräch gesendet.

Gezielt senden

Eine Bedingung in natürlicher Sprache („nur wenn der Anrufer eine Störung meldet“) entscheidet, welche Anrufe die Anfrage auslösen. Mehrere Aktionen können auf unterschiedliche Systeme oder Endpunkte zeigen.

Anbindung eines Ticketsystems

Jedes Ticketsystem mit HTTP-API oder eingehendem Webhook kann Anrufe empfangen — direkt, ohne Software dazwischen. Auf Ihrer Seite wird benötigt:

Ein Endpunkt, der aus dem Internet per HTTPS erreichbar ist und JSON annimmt.
Zugangsdaten dafür (API-Schlüssel, Token oder Basic Auth), eingetragen als Header in der Aktion.
Falls Sie nach Adresse filtern — die beiden IP-Adressen oben auf Ihrer Whitelist.

Danach in der Aktion:

Eigene Felder definieren. Legen Sie Abruf-Variablen an, etwa Kundennummer, Ticketkategorie, Priorität, Rückruf gewünscht. Der Agent füllt sie aus dem Gespräch.
Den Body schreiben — in der Struktur Ihrer Ticket-API, mit den Variablen an den passenden Stellen.
Nur meine Felder senden einschalten.
API-Konfiguration testen klicken, anschließend einen Testanruf führen.

Den Body für Ihr System bereiten wir gern gemeinsam mit Ihnen vor.

Testen

Verbindungstest. Die Schaltfläche API-Konfiguration testen in der Aktion sendet sofort eine Beispielanfrage und zeigt, ob Ihr Endpunkt erreicht wurde.

Test der Wiederholungen — um den Mechanismus selbst zu sehen:

Stellen Sie in der Aktion unter Wiederholungen bei Fehlern einen kurzen Zeitplan ein, zum Beispiel drei Pausen von je 1 Minute.
Stoppen Sie Ihren Endpunkt oder sperren Sie unsere Adressen in der Firewall.
Führen Sie einen Testanruf beim Agenten durch.
Öffnen Sie CRM → Kommunikation: Der Eintrag zeigt Wird wiederholt, den fehlgeschlagenen Versuch mit seinem Fehler und den Zeitpunkt des nächsten.
Starten Sie den Endpunkt wieder (oder heben Sie die Sperre auf). Der nächste Versuch stellt den Anruf zu und der Eintrag wechselt auf Zugestellt — oder Sie klicken auf Erneut senden, um sofort zuzustellen.

Checkliste für Ihren Endpunkt

Antworten Sie mit 2xx, sobald die Anfrage gespeichert ist; die eigentliche Verarbeitung folgt danach.
Behandeln Sie X-Hanc-Delivery-Id als Idempotenzschlüssel.
Antworten Sie mit 4xx/5xx, wenn Sie die Anfrage nicht annehmen konnten — wir kommen wieder.
Halten Sie das Zertifikat gültig und die beiden Quelladressen freigegeben.

Was gesendet wird — und wann​

Wenn Ihr Server nicht erreichbar ist​

Zeitplan der Wiederholungen​

Ihr eigener Zeitplan​

Nach dem letzten Versuch​

Benachrichtigung bei Fehlern​

Zustellprotokoll​

Netzwerk & Firewall​

Format der Anfrage​

Header​

Authentifizierung​

Die Anfrage für Ihr System gestalten​

Variablen​

Body​

Nur Ihre Felder​

Gezielt senden​

Anbindung eines Ticketsystems​

Testen​

Checkliste für Ihren Endpunkt​