> 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/anbindungen-and-integrationen/webhooks.md). # Webhooks Mit Webhooks leiten Sie Gesprächsdaten automatisch an externe Systeme weiter. So übernehmen Sie Informationen aus Anrufen direkt in bestehende Prozesse, etwa in ein CRM, ein Ticketsystem oder ein internes Reporting. Webhooks kommen immer dann zum Einsatz, wenn nach einem Gespräch automatisch etwas passieren soll, ohne dass Daten manuell übertragen werden. {% hint style="info" %} **Hinweis:** Für komplexere Anbindungen unterstützen wir Sie im Rahmen unseres Enterprise-Angebots. [**Termin für individuelle Integrationen vereinbaren**](https://www.sipgate.ai/demo-buchen), um passende Lösungen gemeinsam zu besprechen. {% endhint %} ### Wofür werden Webhooks genutzt? Typische Anwendungsfälle sind die Übergabe von Gesprächszusammenfassungen an ein CRM, das automatische Erstellen von Support-Tickets nach einem Anruf oder die Weiterleitung von Klassifikationen und Themen an Analyse- oder Reporting-Tools. Auch interne Workflows lassen sich so anstoßen, etwa Benachrichtigungen an Teams oder das Anlegen von Aufgaben. ### Voraussetzungen Sie benötigen eine Ziel-URL, an die die Daten gesendet werden. Das empfangende System muss HTTP-POST-Requests mit einer JSON-Payload verarbeiten können. {% hint style="info" %} Webhooks stehen für sipgate sona ab dem Tarif Starter zur Verfügung. Mehr dazu unter [Tarife & Kosten](/tarife-and-kosten/sipgate-sona-tarife-and-kosten.md). {% endhint %} ### Webhooks einrichten #### Wo finde ich Webhooks? * **sipgate sona:** Agentenübersicht öffnen und Webhooks aus der Bibliothek in der Seitenleiste per Drag-and-drop auf Ihren Agent ziehen. * **AI Agents:** Accountverwaltung → AI Agents → Agent auswählen → Navigationseintrag Webhooks. {% hint style="info" %} **Hinweis:** Solange kein Webhook eingerichtet ist, erscheint in der Agentenübersicht auch keine Webhook-Karte. Den ersten Webhook legen Sie deshalb immer über die Bibliothek an. {% endhint %} {% stepper %} {% step %} Hinterlegen Sie eine oder mehrere Webhook-URLs, an die nach Abschluss eines Anrufs automatisch Gesprächsdaten gesendet werden. {% endstep %} {% step %} Nehmen Sie optional zusätzliche Einstellungen vor, zum Beispiel eigene HTTP-Header. {% endstep %} {% endstepper %} Die Änderungen werden nach dem Speichern für alle folgenden Gespräche des Agents angewendet. ### Wie Webhooks funktionieren Nach Abschluss eines Anrufs erstellt sipgate sona ein Gesprächsprotokoll. Anschließend werden die Gesprächsdaten automatisch per HTTP-POST an die hinterlegte Webhook-URL gesendet. Die Daten werden als JSON-Payload übermittelt und können im Zielsystem gespeichert oder weiterverarbeitet werden. Ein typischer Ablauf: Ein Anruf endet, das Gespräch wird zusammengefasst, und die Informationen gehen direkt an das angebundene System. Ihr Team hat die relevanten Daten sofort zur Verfügung. #### Welche Daten werden übertragen? Der Webhook enthält unter anderem Metadaten zum Anruf, Informationen zu durchlaufenen Playbooks sowie eine Zusammenfassung des Gesprächs inklusive erkannter Themen. {% tabs %} {% tab title="ResposeType" %} ```javascript type WebhookPayload = { version: "v1" | "v2"; call: { id: string; from: string; // Telefonnummer mit "+"-Prefix, z.B. "+4921161234567" to: string; // Telefonnummer mit "+"-Prefix, z.B. "+4930987654321" startTime: number; // Epoch Millisekunden endTime: number; // Epoch Millisekunden duration: number; // Dauer in Sekunden 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; // Vollständige Transkription als Text chunks: { speaker: "caller" | "callee"; startTime: number; // Epoch Millisekunden endTime: number; // Epoch Millisekunden 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": "Anruf zu einer verzögerten Bestellung.", "keyPoints": [ "Nachfrage zum Bestellstatus", "Identifikation nicht erfolgreich" ], "topics": [ "order status", "customer service" ] }, "callScenarios": [ { "name": "Bestellstatus", "smartAnswers": [ { "setName": "Kundendaten", "setItems": [ { "question": "Wie lautet die Bestellnummer?", "answer": "B-2024-1234", "title": "Bestellnummer" } ] } ] } ], "transcription": { "content": "Guten Tag, ich rufe an wegen meiner Bestellung...", "chunks": [ { "speaker": "caller", "startTime": 1703862000000, "endTime": 1703862010000, "content": "Guten Tag, ich rufe an wegen meiner Bestellung." }, { "speaker": "callee", "startTime": 1703862011000, "endTime": 1703862020000, "content": "Guten Tag, können Sie mir Ihre Bestellnummer nennen?" } ] } } } ``` {% endtab %} {% endtabs %} **Optionale Felder** * `assist.summary` | Nur vorhanden, wenn eine Zusammenfassung erstellt wurde * `assist.callScenarios` | Nur vorhanden, wenn Playbooks durchlaufen wurden * `assist.transcription` | Nur vorhanden, wenn die Transkript-Speicherung aktiviert ist Die vollständige Payload kann zusätzlich Informationen aus Playbooks enthalten, etwa erfasste Antworten oder Klassifikationen. #### Sicherheit Damit nur Requests von sipgate verarbeitet werden, sollten Sie die Quell-IP-Adresse der eingehenden Webhook-Requests prüfen. Die Requests stammen von diesen beiden Adressen: * `217.116.118.254` * `212.9.46.32` Hinterlegen Sie **beide** Adressen in der Allow List des empfangenden Systems. #### Einordnung Webhooks liefern die Grundlage für Automatisierung, übernehmen aber selbst keine Verarbeitung. Was mit den gesendeten Daten passiert, legen Sie im Zielsystem fest. In Kombination mit Playbooks, Gesprächsprotokollen und Analysen bauen Sie so durchgängige Abläufe auf. Für komplexere Anbindungen unterstützen wir Sie im Rahmen des Enterprise-Tarifs. [**Termin für individuelle Integrationen vereinbaren**](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/anbindungen-and-integrationen/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.