> For the complete documentation index, see [llms.txt](https://help.sipgate.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.de/conversation-intelligence/webhooks-einrichten.md).
# Webhooks einrichten
Mit Webhooks senden Sie Ereignisse und Ergebnisse aus Conversation Intelligence automatisch an Ihr CRM oder andere externe Systeme.
#### Was ist ein Webhook?
Ein Webhook sendet automatisch eine Benachrichtigung an eine von Ihnen festgelegte Ziel-URL, sobald ein Ereignis in einem ausgewählten Channel auftritt. Sie legen dabei fest, welche Channels überwacht werden und wohin die Daten gesendet werden sollen. Der Webhook wird nach Gesprächsende ausgelöst, sobald die KI-Auswertung abgeschlossen ist. Die Daten kommen als JSON per HTTP POST bei Ihrem System an.
Typische Anwendungsfälle:
* **CRM-Integration:** Gesprächsnotizen und Zusammenfassungen in Kundendatensätze übernehmen
* **Support-Systeme:** Tickets nach eingehenden Anrufen erstellen
* **Analytics:** Klassifikationen und Custom Fields an ein Reporting-Tool weiterleiten
#### Was benötige ich für die Einrichtung?
* Admin-Rechte in Ihrem sipgate Account
* Einen Account, der auf Neo PBX läuft. Webhooks funktionieren nur mit Neo-PBX-Accounts.
* Eine oder mehrere Ziel-URLs, die HTTP-POST-Requests mit JSON-Nutzlast verarbeiten können. Die Anfragen werden mit `Transfer-Encoding: chunked` gesendet, Ihr System muss das unterstützen.
* Ein System, das Anfragen von der sipgate IP-Adresse `217.116.118.254` annimmt. Nehmen Sie diese Adresse in Ihre Allow List auf.
Ihr System sollte jede Anfrage mit HTTP 200 und leerem Body beantworten. Der Antwort-Body wird nicht ausgewertet.
#### Wie richte ich einen Webhook ein?
{% stepper %}
{% step %}
## Webhook hinzufügen
Gehen Sie zu **Conversation Intelligence → Webhooks** und klicken Sie auf **+ Hinzufügen**.
{% endstep %}
{% step %}
## Namen vergeben
Vergeben Sie einen aussagekräftigen **Namen** für den Webhook (z. B. „Kundenbetreuung Core"), damit Sie ihn später wiedererkennen.
{% endstep %}
{% step %}
## Ziel-URLs eintragen
Tragen Sie eine oder mehrere **Ziel-URLs** ein, an die die Ereignisse gesendet werden sollen. Über **+ Weitere URL** ergänzen Sie zusätzliche Ziele, so senden Sie dieselben Ereignisse gleichzeitig an mehrere Systeme.
{% endstep %}
{% step %}
## Channels auswählen
Wählen Sie die **Channels** aus, deren Ereignisse an diesen Webhook gesendet werden sollen. Zur Auswahl stehen geteilte Channels, persönliche Channels und Contact Center Channels.
{% endstep %}
{% step %}
## Webhook aktivieren und speichern
Aktivieren Sie den Webhook über die Checkbox **Webhook aktivieren** und klicken Sie auf **Speichern**.
{% endstep %}
{% endstepper %}
Ihr neuer Webhook erscheint danach in der Übersicht mit Name, Ziel-URL, zugeordneten Channels und Status.
#### Wie verwalte ich Webhooks?
In der Übersicht können Sie jeden Webhook jederzeit anpassen:
* **Bearbeiten:** Name, URLs oder zugeordnete Channels ändern
* **Header hinzufügen:** Zusätzliche HTTP-Header definieren, z. B. für die Authentifizierung gegenüber Ihrem Zielsystem
* **Deaktivieren:** Den Webhook vorübergehend pausieren, ohne ihn zu löschen
* **Löschen:** Den Webhook endgültig entfernen
Der Status (z. B. „Aktiv") zeigt Ihnen auf einen Blick, ob ein Webhook aktuell Ereignisse versendet.
#### Wie sieht die Payload aus?
Die Nutzlast enthält die Call-Metadaten (`call`), die KI-Auswertung (`assist`) und einen Hinweis zur Kennzeichnung (`meta`). Aktuell ist die Version `"2.0"` im Einsatz.
| Feld | Beschreibung |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | Version des Payload-Formats, aktuell `"2.0"` |
| `call.id` | Eindeutige Call-ID |
| `call.accountId` | ID Ihres Accounts |
| `call.entityId` | ID des Channels bzw. Endpunkts, über den der Anruf lief |
| `call.from`, `call.to` | Rufnummern von Anrufer und Angerufenem im E.164-Format ohne führendes `+` |
| `call.direction` | `"IN"` für eingehend, `"OUT"` für ausgehend |
| `call.startTime`, `call.endTime` | Beginn und Ende des Anrufs im ISO-8601-Format |
| `call.duration` | Gesprächsdauer in Millisekunden |
| `assist.provider.llm` | Verwendeter KI-Anbieter |
| `assist.transcription` | Volltext (`content`) und einzelne Abschnitte (`chunks`) mit Sprecher (`CALLER`, `CALLEE` oder `UNKNOWN`), Text und Zeitangaben in Millisekunden |
| `assist.agentTalkRatio` | Redeanteil des Mitarbeitenden am Gespräch in Prozent |
| `assist.variables` | Die erhobenen Custom Fields, siehe unten |
| `meta.aiGenerated` | `true`, wenn die Inhalte KI-generiert sind |
Ist eine KI-Funktion nicht erfolgreich gewesen, ist das zugehörige Feld `null`. Ist zum Beispiel die Transkription fehlgeschlagen, steht dort `"transcription": null`.
In der Transkription steht `CALLER` für die Person, die das Gespräch startet, bei ausgehenden Anrufen also Ihr Mitarbeitender, bei eingehenden Anrufen die externe Person. `CALLEE` ist die Person, die den Anruf annimmt. `UNKNOWN` kennzeichnet Abschnitte, die sich keinem Sprecher zuordnen lassen.
#### Wie erscheinen meine Custom Fields in der Payload?
Alle erhobenen [Custom Fields](broken://pages/7c2a843ba384e62c9e432c53d1d133022e2e306d), vordefinierte wie eigene, stehen in der Liste `assist.variables`. Auch die Zusammenfassung (`summary`), die Themen (`topics`) und der Anrufgrund (`call_intent`) sind vordefinierte Custom Fields und stehen dort. Jeder Eintrag enthält:
| Feld | Beschreibung |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `variableId` | Eindeutige ID des Custom Fields |
| `name` | Name des Feldes. Vordefinierte Felder haben technische Namen wie `customer_number`, `first_name` oder `call_intent`, eigene Felder behalten den Namen, den Sie vergeben haben. |
| `type` | Datentyp: `STRING`, `DATE`, `TIME` oder `BOOLEAN` |
| `format` | Format bei Datum und Uhrzeit (`YYYY-MM-DD`, `HH:MM`), sonst `null` |
| `values` | Die erhobenen Werte als Liste von Texten. Wurde im Gespräch nichts gefunden, ist die Liste leer. |
| `value` | Bleibt aktuell leer. Die Werte stehen in `values`. |
Welcher Datentyp zu welchem Ausgabeformat gehört:
| Ausgabeformat | `type` | Beispiel für `values` |
| ------------- | --------- | -------------------------- |
| Text | `STRING` | `["Kalender-API löschen"]` |
| Auswahl | `STRING` | `["Integrationen"]` |
| Datum | `DATE` | `["2026-11-05"]` |
| Uhrzeit | `TIME` | `["14:30"]` |
| Ja/Nein | `BOOLEAN` | `["false"]` |
Beispiel (Aufbau wie in der Praxis, alle Inhalte frei erfunden):
```json
{
"version": "2.0",
"call": {
"id": "pbx-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"from": "4921163553400",
"to": "4921163553401",
"startTime": "2026-10-19T12:58:43.863Z",
"endTime": "2026-10-19T13:01:40.585Z",
"duration": 176722,
"direction": "IN",
"accountId": "1234567",
"entityId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"assist": {
"provider": {
"llm": "AZURE"
},
"transcription": {
"content": "Callee: Guten Tag, Beispiel GmbH Support, Sie sprechen mit Max.\nCaller: Guten Tag, hier ist Erika Mustermann.\nCaller: Meine Kundennummer ist 12345. Ich habe eine Frage zu meiner letzten Rechnung.\nCallee: Das schaue ich mir gern an. Einen Moment bitte.\nCallee: Der Betrag ist korrekt, da ein Zusatzpaket gebucht wurde. Einen Tarifwechsel kann ich Ihnen anbieten.\nCaller: Gern, bitte schicken Sie mir die Optionen per E-Mail. Am 5. November um 14:30 Uhr passt ein Rückruf.\nCallee: Das mache ich. Vielen Dank für Ihren Anruf.\nCaller: Danke, auf Wiederhören.",
"chunks": [
{
"speaker": "CALLEE",
"startTime": 709,
"endTime": 2590,
"content": "Guten Tag, Beispiel GmbH Support, Sie sprechen mit Max."
},
{
"speaker": "CALLER",
"startTime": 3459,
"endTime": 5880,
"content": "Guten Tag, hier ist Erika Mustermann."
},
{
"speaker": "CALLER",
"startTime": 6600,
"endTime": 12360,
"content": "Meine Kundennummer ist 12345. Ich habe eine Frage zu meiner letzten Rechnung."
},
{
"speaker": "CALLEE",
"startTime": 14200,
"endTime": 19400,
"content": "Das schaue ich mir gern an. Einen Moment bitte."
},
{
"speaker": "CALLEE",
"startTime": 41300,
"endTime": 52100,
"content": "Der Betrag ist korrekt, da ein Zusatzpaket gebucht wurde. Einen Tarifwechsel kann ich Ihnen anbieten."
},
{
"speaker": "CALLER",
"startTime": 52800,
"endTime": 61500,
"content": "Gern, bitte schicken Sie mir die Optionen per E-Mail. Am 5. November um 14:30 Uhr passt ein Rückruf."
},
{
"speaker": "CALLEE",
"startTime": 63000,
"endTime": 66200,
"content": "Das mache ich. Vielen Dank für Ihren Anruf."
},
{
"speaker": "CALLER",
"startTime": 66000,
"endTime": 68400,
"content": "Danke, auf Wiederhören."
}
]
},
"agentTalkRatio": 32,
"variables": [
{
"variableId": "00000000-0000-4000-8000-000000000001",
"name": "customer_number",
"value": "",
"type": "STRING",
"format": null,
"values": [
"12345"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000002",
"name": "email",
"value": "",
"type": "STRING",
"format": null,
"values": []
},
{
"variableId": "00000000-0000-4000-8000-000000000003",
"name": "phone_number",
"value": "",
"type": "STRING",
"format": null,
"values": []
},
{
"variableId": "00000000-0000-4000-8000-000000000004",
"name": "reference_number",
"value": "",
"type": "STRING",
"format": null,
"values": []
},
{
"variableId": "00000000-0000-4000-8000-000000000005",
"name": "address",
"value": "",
"type": "STRING",
"format": null,
"values": []
},
{
"variableId": "00000000-0000-4000-8000-000000000006",
"name": "company_name",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Beispiel GmbH"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000007",
"name": "appointment_date",
"value": "",
"type": "DATE",
"format": "YYYY-MM-DD",
"values": [
"2026-11-05"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000008",
"name": "first_name",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Erika"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000009",
"name": "last_name",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Mustermann"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000010",
"name": "salutation",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Frau"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000011",
"name": "call_intent",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Rechnungsfrage und Tarifwechsel"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000012",
"name": "topics",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Rechnung",
"Zusatzpaket",
"Tarifwechsel"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000013",
"name": "summary",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Die Kundin fragt nach ihrer letzten Rechnung. Der Betrag ist korrekt, da ein Zusatzpaket gebucht wurde. Sie interessiert sich für einen Tarifwechsel und wünscht die Optionen per E-Mail sowie einen Rückruf am 5. November um 14:30 Uhr."
]
},
{
"variableId": "00000000-0000-4000-8000-000000000014",
"name": "appointment_time",
"value": "",
"type": "TIME",
"format": "HH:MM",
"values": [
"14:30"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000015",
"name": "Kategorie",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Rechnung",
"Tarif"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000016",
"name": "Anliegen gelöst",
"value": "",
"type": "STRING",
"format": null,
"values": [
"OFFEN"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000017",
"name": "Abwanderungssignal",
"value": "",
"type": "BOOLEAN",
"format": null,
"values": [
"false"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000018",
"name": "Beschwerde",
"value": "",
"type": "BOOLEAN",
"format": null,
"values": []
}
]
},
"meta": {
"aiGenerated": true
}
}
```
#### Worin unterscheidet sich der CI Webhook vom AI Assist Webhook?
Der CI Webhook wird hier unter Conversation Intelligence eingerichtet und gilt für die von Ihnen gewählten Channels. Der AI Assist Webhook wird dagegen in der sipgate Desktop App eingerichtet und überträgt die AI-Assist-Ergebnisse eines einzelnen Channels. Eine Anleitung finden Sie unter [Wie richte ich den sipgate AI Assist Webhook ein?](https://help.sipgate.de/cloud-telefonanlage/sipgate-nutzen/die-sipgate-app/wie-richte-ich-den-sipgate-ai-assist-webhook-ein).
{% hint style="warning" %}
Webhooks enthalten Inhalte aus Gesprächen und damit potenziell personenbezogene Daten. Stellen Sie sicher, dass Ihr Zielsystem diese Daten datenschutzkonform verarbeitet. Mehr dazu unter [Datenschutz](broken://pages/0121ff07f4cee407c4c7e58845d04f75ba1700f1).
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.sipgate.de/conversation-intelligence/webhooks-einrichten.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
