> 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/ai-agents/en/connections-and-integrations/webhooks.md).

# Webhooks

Webhooks can be used to automatically forward call data from sipgate AI Agents to external systems. This allows information from calls to be fed 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 a meeting 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 call 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

To use webhooks, you need a destination URL to which the data should be sent. The receiving system must be able to process HTTP POST requests with a JSON payload.

### Set up webhooks

{% stepper %}
{% step %}
Open your **account management.**
{% endstep %}

{% step %}
Go to **AI Agents,** select the desired agent or create a new one. In the agent's user interface, you will find the navigation item **Webhooks**.
{% endstep %}

{% step %}
Store one or more webhook URLs there, to which call data is automatically sent after a call is completed.
{% endstep %}

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

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

### How webhooks work

After a call ends, sipgate AI Agents creates a call log. The call 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 destination system.

A typical flow looks like this: A call ends, the conversation is summarized, and the information is forwarded directly to a connected system. Your team has the relevant data immediately available, without manual intervention.

#### Which data is transferred?

The webhook contains, among other things, metadata about the call, information about playbooks that were run, as well as a summary of the conversation including recognized topics.\
A shortened example of a payload looks like this:

{% 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 regarding 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": "Good day, I'm calling about my order...",
      "chunks": [
        {
          "speaker": "caller",
          "startTime": 1703862000000,
          "endTime": 1703862010000,
          "content": "Good day, I'm calling about my order."
        },
        {
          "speaker": "callee",
          "startTime": 1703862011000,
          "endTime": 1703862020000,
          "content": "Good day, could you tell 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 transcript storage is enabled

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

#### Security

To ensure that only requests from sipgate AI Agents are processed, the source IP address of incoming webhook requests should be checked.\
The requests come from the following IP addresses:

* `217.116.118.254`
* `212.9.46.32`

This address should be stored in the receiving system's allow list to prevent unauthorized access.

#### Classification

Webhooks provide the basis for automation, but do not perform any processing themselves. What happens to the sent data is determined in the respective destination system. In combination with playbooks, call logs, and analyses, end-to-end automated processes can be built in this way.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.sipgate.de/ai-agents/en/connections-and-integrations/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.