> For the complete documentation index, see [llms.txt](https://help.sipgate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.com/documentation/en/connections-and-integrations/webhooks.md).

# Webhooks

With webhooks, you automatically forward conversation data to external systems. This lets you transfer information from calls directly into existing processes, such as a CRM, a ticketing system, or internal reporting.

Webhooks are used whenever something should happen automatically after a conversation, without data having to be transferred manually.

{% hint style="info" %}
**Note:** For more complex integrations, we support you as part of our Enterprise offering. [**Schedule an appointment for custom integrations**](https://www.sipgate.ai/demo-buchen), to discuss suitable solutions together.
{% endhint %}

### What are webhooks used for?

Typical use cases include passing conversation summaries to a CRM, automatically creating support tickets after a call, or forwarding classifications and topics to analysis or reporting tools. Internal workflows can also be triggered this way, such as notifications to teams or creating tasks.

### Requirements

You need a target URL to which the data is sent. The receiving system must be able to process HTTP POST requests with a JSON payload.

{% hint style="info" %}
Webhooks are available for sipgate sona starting with the Starter plan. More on this under [Plans & pricing](https://help.sipgate.com/documentation/en/plans-and-pricing/sipgate-sona-tarife-and-kosten.md).
{% endhint %}

### Set up webhooks

#### Where can I find webhooks?

* **sipgate sona:** Open the agent overview and drag and drop webhooks from the library in the sidebar onto your agent.
* **AI Agents:** Account management → AI Agents → Select agent → Webhooks navigation item.

{% hint style="info" %}
**Note:** As long as no webhook has been set up, no webhook card will appear in the agent overview. That is why you always create the first webhook via the library.
{% endhint %}

{% stepper %}
{% step %}
Store one or more webhook URLs to which conversation data is automatically sent after a call ends.
{% endstep %}

{% step %}
Optionally make additional settings, for example custom HTTP headers.
{% endstep %}
{% endstepper %}

The changes are applied to all subsequent conversations of the agent after saving.

### How webhooks work

After a call ends, sipgate sona creates a call log. The conversation data is then automatically sent via HTTP POST to the stored webhook URL. The data is transmitted as a JSON payload and can be stored or further processed in the target system.

A typical flow: A call ends, the conversation is summarized, and the information goes directly to the connected system. Your team has the relevant data immediately available.

#### Which data is transmitted?

The webhook contains, among other things, metadata about the call, information about playbooks that were run, and a summary of the conversation including recognized topics.

{% tabs %}
{% tab title="ResposeType" %}

```javascript
type WebhookPayload = {
  version: "v1" | "v2";
  call: {
    id: string;
    from: string;               // phone number with "+" prefix, e.g. "+4921161234567"
    to: string;                 // phone number with "+" prefix, e.g. "+4930987654321"
    startTime: number;          // epoch milliseconds
    endTime: number;            // epoch milliseconds
    duration: number;           // duration in seconds
    direction: "in" | "out";
    users: {
      userId: string;
      accountId: string;
      fullUserId: string;
      firstName: string;
      lastName: string;
      fullName: string;
    }[];
  };
  assist?: {
    summary?: {
      content: string;
      keyPoints: string[];
      topics: string[];
    };
    callScenarios?: {
      name: string;
      smartAnswers: {
        setName: string;
        setItems: {
          question: string;
          answer: string;
          title?: string;
        }[];
      }[];
    }[];
    transcription?: {
      content: string;          // full transcription as text
      chunks: {
        speaker: "caller" | "callee";
        startTime: number;      // epoch milliseconds
        endTime: number;        // epoch milliseconds
        content: string;
      }[];
    };
  };
};
```

{% endtab %}

{% tab title="Example JSON" %}

```json
{
  "version": "v1",
  "call": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "from": "+4921161234567",
    "to": "+4930987654321",
    "startTime": 1703862000000,
    "endTime": 1703862300000,
    "duration": 300,
    "direction": "in",
    "users": []
  },
  "assist": {
    "summary": {
      "content": "Call about a delayed order.",
      "keyPoints": [
        "Inquiry about order status",
        "Identification unsuccessful"
      ],
      "topics": [
        "order status",
        "customer service"
      ]
    },
    "callScenarios": [
      {
        "name": "Order status",
        "smartAnswers": [
          {
            "setName": "Customer data",
            "setItems": [
              {
                "question": "What is the order number?",
                "answer": "B-2024-1234",
                "title": "Order number"
              }
            ]
          }
        ]
      }
    ],
    "transcription": {
      "content": "Hello, I'm calling about my order...",
      "chunks": [
        {
          "speaker": "caller",
          "startTime": 1703862000000,
          "endTime": 1703862010000,
          "content": "Hello, I'm calling about my order."
        },
        {
          "speaker": "callee",
          "startTime": 1703862011000,
          "endTime": 1703862020000,
          "content": "Hello, could you give me your order number?"
        }
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

**Optional fields**

* `assist.summary` | Only present if a summary was created
* `assist.callScenarios` | Only present if playbooks were run
* `assist.transcription` | Only present if transcription storage is enabled

The full payload can additionally contain information from playbooks, such as collected answers or classifications.

#### Security

To ensure that only requests from sipgate are processed, you should check the source IP address of incoming webhook requests. The requests originate from these two addresses:

* `217.116.118.254`
* `212.9.46.32`

Store **both** addresses in the receiving system's allow list.

#### Classification

Webhooks provide the basis for automation, but do not perform any processing themselves. What happens to the sent data is defined in the target system. In combination with playbooks, call logs, and analyses, you can build end-to-end workflows.

For more complex integrations, we support you as part of the Enterprise plan. [**Schedule an appointment for custom integrations**](https://www.sipgate.ai/demo-buchen)**.**


---

# 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.com/documentation/en/connections-and-integrations/webhooks.md?ask=<question>&goal=<user_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.
