> 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/conversation-intelligence-en/set-up-webhooks.md).
# Set up webhooks
With webhooks, you automatically send events and results from Conversation Intelligence to your CRM or other external systems.
#### What is a webhook?
A webhook automatically sends a notification to a target URL you define as soon as an event occurs in a selected channel. You specify which channels are monitored and where the data should be sent. The webhook is triggered after the call ends, once the AI analysis is complete. The data reaches your system as JSON via HTTP POST.
Typical use cases:
* **CRM integration:** Transfer call notes and summaries into customer records
* **Support systems:** Create tickets for incoming calls
* **Analytics:** Forward classifications and custom fields to a reporting tool
#### What do I need for setup?
* Admin rights in your sipgate account
* An account running on Neo PBX. Webhooks only work with Neo PBX accounts.
* One or more target URLs that can process HTTP POST requests with JSON payloads. The requests are sent with `Transfer-Encoding: chunked` sent; your system must support this.
* A system that accepts requests from the sipgate IP address `217.116.118.254` Add this address to your allow list.
Your system should respond to each request with HTTP 200 and an empty body. The response body is not evaluated.
#### How do I set up a webhook?
{% stepper %}
{% step %}
## Add webhook
Go to **Conversation Intelligence → Webhooks** and click **+ Add**.
{% endstep %}
{% step %}
## Assign a name
Give it a meaningful **name** for the webhook (e.g. “Customer Support Core”), so you can recognize it later.
{% endstep %}
{% step %}
## Enter target URLs
Enter one or more **target URLs** to which the events should be sent. Through **+ More URL** you can add additional targets; this sends the same events to multiple systems at the same time.
{% endstep %}
{% step %}
## Select channels
Select the **channels** whose events should be sent to this webhook. Available are shared channels, personal channels, and contact center channels.
{% endstep %}
{% step %}
## Activate and save the webhook
Enable the webhook using the checkbox **Enable webhook** and click **Save**.
{% endstep %}
{% endstepper %}
Your new webhook will then appear in the overview with name, target URL, assigned channels, and status.
#### How do I manage webhooks?
In the overview, you can adjust each webhook at any time:
* **Edit:** change the name, URLs, or assigned channels
* **Add header:** Define additional HTTP headers, e.g. for authentication against your target system
* **Disable:** pause the webhook temporarily without deleting it
* **Delete:** remove the webhook permanently
The status (e.g. “Active”) shows you at a glance whether a webhook is currently sending events.
#### What does the payload look like?
The payload contains the call metadata (`call`), the AI analysis (`assist`) and a marking hint (`meta`). The current version is `"2.0"` in use.
| Field | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | Version of the payload format, currently `"2.0"` |
| `call.id` | Unique call ID |
| `call.accountId` | Your account ID |
| `call.entityId` | ID of the channel or endpoint through which the call ran |
| `call.from`, `call.to` | Phone numbers of caller and callee in E.164 format without a leading `+` |
| `call.direction` | `"IN"` for incoming, `"OUT"` for outgoing |
| `call.startTime`, `call.endTime` | Start and end of the call in ISO-8601 format |
| `Call duration in milliseconds` | Call duration in milliseconds |
| `assist.provider.llm` | AI provider used |
| `assist.transcription` | Full text (`content`) and individual sections (`chunks`) with speaker (`CALLER`, `CALLEE` or `UNKNOWN`), text and timestamps in milliseconds |
| `assist.agentTalkRatio` | Share of the conversation spoken by the employee in percent |
| `assist.variables` | The collected custom fields, see below |
| `meta.aiGenerated` | `true`, if the content was AI-generated |
If an AI function was not successful, the corresponding field is `null`. For example, if transcription failed, it says `"transcription": null`.
In the transcription, `CALLER` marks the person who starts the conversation; in outgoing calls, therefore, your employee, and in incoming calls, the external person. `CALLEE` is the person who answers the call. `UNKNOWN` marks sections that cannot be assigned to a speaker.
#### How do my custom fields appear in the payload?
All collected ones [Custom Fields](broken://pages/f5356f5e4741b153b3ec3ac8a330295c3b2cc309), both predefined and custom, are listed in the `assist.variables`list.`summary`), the topics (`topics`) and the call reason (`call_intent`) are also predefined custom fields and are listed there. Each entry contains:
| Field | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variableId` | Unique ID of the custom field |
| `name` | Name of the field. Predefined fields have technical names such as `customer_number`, `first_name` or `call_intent`, custom fields retain the name you assigned. |
| `type` | Data type: `STRING`, `DATE`, `TIME` or `BOOLEAN` |
| `format` | Format for date and time (`YYYY-MM-DD`, `HH:MM`), otherwise `null` |
| `values` | The collected values as a list of texts. If nothing was found in the conversation, the list is empty. |
| `value` | Currently remains empty. The values are in `values`. |
Which data type belongs to which output format:
| Output format | `type` | Example for `values` |
| ------------- | --------- | ------------------------- |
| Text | `STRING` | `["delete calendar API"]` |
| Selection | `STRING` | `["Integrations"]` |
| Date | `DATE` | `["2026-11-05"]` |
| Time | `TIME` | `["14:30"]` |
| Yes/No | `BOOLEAN` | `["false"]` |
Example (structured as in practice, all contents freely invented):
```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: Hello, Example Ltd. Support, you're speaking with Max.\nCaller: Hello, this is Erika Mustermann.\nCaller: My customer number is 12345. I have a question about my latest invoice.\nCallee: I'd be happy to look into that. One moment please.\nCallee: The amount is correct because an add-on package was booked. I can offer you a plan change.\nCaller: Gladly, please send me the options by email. November 5 at 2:30 PM works for a callback.\nCallee: I'll do that. Thank you for your call.\nCaller: Thank you, goodbye.",
"chunks": [
{
"speaker": "CALLEE",
"startTime": 709,
"endTime": 2590,
"content": "Good day, Example Ltd. Support, you're speaking with Max."
},
{
"speaker": "CALLER",
"startTime": 3459,
"endTime": 5880,
"content": "Good day, this is Erika Mustermann."
},
{
"speaker": "CALLER",
"startTime": 6600,
"endTime": 12360,
"content": "My customer number is 12345. I have a question about my latest invoice."
},
{
"speaker": "CALLEE",
"startTime": 14200,
"endTime": 19400,
"content": "I'd be happy to look into that. One moment please."
},
{
"speaker": "CALLEE",
"startTime": 41300,
"endTime": 52100,
"content": "The amount is correct because an add-on package was booked. I can offer you a plan change."
},
{
"speaker": "CALLER",
"startTime": 52800,
"endTime": 61500,
"content": "Gladly, please send me the options by email. November 5 at 2:30 PM works for a callback."
},
{
"speaker": "CALLEE",
"startTime": 63000,
"endTime": 66200,
"content": "I'll do that. Thank you for your call."
},
{
"speaker": "CALLER",
"startTime": 66000,
"endTime": 68400,
"content": "Thank you, goodbye."
}
]
},
"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": [
"Example Ltd."
]
},
{
"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": [
"Ms."
]
},
{
"variableId": "00000000-0000-4000-8000-000000000011",
"name": "call_intent",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Billing inquiry and plan change"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000012",
"name": "topics",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Invoice",
"Add-on package",
"Plan change"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000013",
"name": "summary",
"value": "",
"type": "STRING",
"format": null,
"values": [
"The customer asks about her latest invoice. The amount is correct because an add-on package was booked. She is interested in a plan change and would like the options by email as well as a callback on November 5 at 2:30 PM."
]
},
{
"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": "Category",
"value": "",
"type": "STRING",
"format": null,
"values": [
"Invoice",
"Plan"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000016",
"name": "Issue resolved",
"value": "",
"type": "STRING",
"format": null,
"values": [
"OPEN"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000017",
"name": "Churn signal",
"value": "",
"type": "BOOLEAN",
"format": null,
"values": [
"false"
]
},
{
"variableId": "00000000-0000-4000-8000-000000000018",
"name": "Complaint",
"value": "",
"type": "BOOLEAN",
"format": null,
"values": []
}
]
},
"meta": {
"aiGenerated": true
}
}
```
#### What is the difference between the CI webhook and the AI Assist webhook?
The CI webhook is set up here under Conversation Intelligence and applies to the channels you selected. The AI Assist webhook, in contrast, is set up in the sipgate Desktop App and transfers the AI Assist results of a single channel. Instructions can be found at [How do I set up the sipgate AI Assist webhook?](https://help.sipgate.de/cloud-telefonanlage/sipgate-nutzen/die-sipgate-app/wie-richte-ich-den-sipgate-ai-assist-webhook-ein).
{% hint style="warning" %}
Webhooks contain content from conversations and therefore potentially personal data. Make sure your target system processes this data in compliance with data protection regulations. More on this at [Privacy](broken://pages/825b447ea55cbbf11355bd3143c076c3cf10c133).
{% 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/conversation-intelligence-en/set-up-webhooks.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.
