Webhooks

Was sind Webhooks?

Webhooks sind automatische HTTP-Anfragen, die HalloPetra an Ihre externen Systeme sendet, wenn bestimmte Ereignisse eintreten — zum Beispiel wenn ein Anruf eingeht, eine Funktion während des Gesprächs ausgelöst wird oder ein Anruf beendet wurde. Sie ermöglichen den Datenaustausch in Echtzeit zwischen Petra und Ihren bestehenden Tools (CRM, ERP, Automatisierungsplattformen wie n8n oder Make, eigene APIs usw.).

Im Gegensatz zu herkömmlichen API-Abfragen, bei denen Ihr System ständig nachfragen muss „Ist etwas passiert?", liefern Webhooks die Daten genau in dem Moment, in dem etwas geschieht. Stellen Sie sich vor, Petra ruft Ihr System an, um Informationen zu übermitteln — anstatt dass Ihr System ständig bei Petra nachfragen muss.

Webhook-Typen

HalloPetra unterstützt vier Webhook-Typen, die jeweils an einem anderen Zeitpunkt im Ablauf ausgelöst werden:

1. Vor dem Anruf (Pre-Call)

Wann wird er ausgelöst: Sofort bei eingehendem Anruf, bevor Petra das Gespräch beginnt.

Zweck: Den Anruf mit externen Daten anreichern. Nutzen Sie diesen Webhook, um den Anrufer in Ihrem CRM nachzuschlagen, Kundenhistorie abzurufen oder Kontodaten zu laden, damit Petra vor dem Gespräch bereits Kontext hat.

Ausführungsmodus:

• Immer — Wird bei jedem eingehenden Anruf ausgeführt

• Bei Bedarf — Wird nur ausgeführt, wenn er mit einer bestimmten Aktion verknüpft ist

Gesendete Daten (Request):

{
  "body": {
    "webhook_id": "<Webhook-ID>",
    "data": {
      "calling_phone_number": "+491234567890",
      "inbound_phone_number": "+4930123456",
      "start_time": "2026-03-24T10:30:00Z"
    }
  }
}

Erwartete Antwort (Response):

{
  "contact": {
    "contact_data_name": "Max Mustermann",
    "contact_data_email": "max@mustermann.de",
    "contact_data_phone": "+491234567890",
    "contact_data_address": "Musterstraße 1, 12345 Musterstadt"
  },
  "other_data": {
    "kundennummer": "K-12345",
    "vertragstyp": "Premium"
  },
  "content": "Bestandskunde seit 2019, Premium-Vertrag, offene Rechnung #4521"
}

So wird die Antwort verwendet:

• contact — Füllt Kontaktdaten vorab aus, sodass Petra nicht danach fragen muss. Felder können auch genutzt werden, um bereits beantwortete Frageschritte auszublenden.

• other_data — Zusätzliche Schlüssel-Wert-Daten, die als Parameter für Bedingungen und Variablenauflösung verfügbar sind.

• content — Freitext-Information, die Petra in Textform mitgeteilt wird. Nutzen Sie dies, um Petra Kontext zu geben wie „Dies ist ein VIP-Kunde" oder „Es gibt ein offenes Support-Ticket."

Timeout: 2,5 Sekunden. Wenn der Webhook nicht rechtzeitig antwortet, fährt Petra ohne die Zusatzdaten fort.

2. Während des Anrufs (During-Call)

Wann wird er ausgelöst: Während eines aktiven Gesprächs, ausgelöst durch einen Funktionsschritt in einer Aufgabe.

Zweck: Ermöglicht Echtzeit-Interaktionen mit externen Systemen, während Petra telefoniert. Nutzen Sie dies für Dokumentensuche, Lagerbestandsprüfungen, Terminverfügbarkeit, Preisberechnungen oder beliebige dynamische Datenabfragen.

So richten Sie es ein:

1. Erstellen Sie einen Während-des-Anrufs-Webhook unter Einstellungen → Webhooks

2. Definieren Sie Webhook-Variablen (Parameter, die Petra während des Gesprächs füllt)

3. Fügen Sie einen Funktionsschritt zu einer Aufgabe hinzu und verknüpfen Sie ihn mit dem Webhook

Gesendete Daten (Request):

{
  "body": {
    "webhook_id": "<Webhook-ID>",
    "call": {
      "calling_phone_number": "+491234567890",
      "inbound_phone_number": "+4930123456",
      "start_time": "2026-03-24T10:30:00Z",
      "call_id": "call_abc123",
      "duration": 45,
      "contact_id": "contact_xyz",
      "messages": [
        { "role": "assistant", "content": "Guten Tag, hier ist Petra..." },
        { "role": "user", "content": "Ich suche ein Ersatzteil..." }
      ],
      "previous_webhook_calls": []
    },
    "parameter": {
      "artikelnummer": "HZ-4521",
      "menge": "2"
    }
  }
}

Das parameter-Objekt enthält die von Ihnen definierten Webhook-Variablen, gefüllt mit Werten, die Petra aus dem Gespräch extrahiert hat.

Erwartete Antwort (Response):

{
  "message": {
    "content": "Das Ersatzteil HZ-4521 ist auf Lager. Der Preis beträgt 45,90 Euro.",
    "message_type": "SAY"
  },
  "contact_updates": {
    "letzte_anfrage": "Ersatzteil HZ-4521"
  }
}

Antwort-Felder:

• message.content — Text, den Petra dem Anrufer vorliest

• message.message_type — "SAY" (Petra spricht den Text laut aus) oder "SILENT" (wird intern verarbeitet, nicht gesprochen)

• contact_updates — Optionale Schlüssel-Wert-Paare zur Aktualisierung des Kontaktdatensatzes

Timeout: 10 Sekunden. Petra wartet auf die Antwort, bevor sie das Gespräch fortsetzt.

3. Nach dem Anruf (Post-Call)

Wann wird er ausgelöst: Nach Beendigung eines Anrufs, sobald Petra ihre Analyse abgeschlossen hat.

Zweck: Anrufergebnisse an externe Systeme übermitteln. Nutzen Sie dies, um CRM-Einträge zu erstellen, Follow-up-Workflows auszulösen, Projektmanagement-Tools zu aktualisieren, Daten an Ihr ERP zu senden oder Anrufe in eigenen Systemen zu protokollieren.

Ausführungsmodus:

• Immer — Wird nach jedem Anruf ausgeführt

• Bei Bedarf — Wird nur ausgeführt, wenn er mit einer bestimmten Aktion einer Aufgabe verknüpft ist

Gesendete Daten (Request):

{
  "body": {
    "webhook_id": "<Webhook-ID>",
    "data": {
      "id": "call_abc123",
      "duration": 125,
      "phone": "+491234567890",
      "topic": "Heizungswartung anfragen",
      "summary": "Kunde möchte einen Termin für die jährliche Heizungswartung. Wunschtermin nächste Woche Dienstag oder Mittwoch.",
      "messages": [
        { "role": "assistant", "content": "Guten Tag..." },
        { "role": "user", "content": "Ich möchte..." }
      ],
      "collected_data": {
        "contact_name": "Max Mustermann",
        "contact_email": "max@mustermann.de",
        "heizungstyp": "Gas-Brennwert",
        "wunschtermin": "Dienstag oder Mittwoch"
      },
      "contact_data": {
        "id": "contact_xyz",
        "name": "Max Mustermann",
        "phone": "+491234567890",
        "email": "max@mustermann.de",
        "address": "Musterstraße 1, 12345 Musterstadt"
      },
      "main_task_id": "task_abc",
      "email_send_to": "info@beispiel.de",
      "forwarded_to": "+4930987654",
      "previous_webhook_calls": []
    }
  }
}

Wichtige Datenfelder:

Timeout: 10 Sekunden.

4. Bei Formulareingang (Form Submission)

Wann wird er ausgelöst: Wenn ein Kontakt ein Formular ausfüllt, das als Follow-up nach einem Anruf gesendet wurde.

Zweck: Formulareinreichungen in externen Systemen verarbeiten — Workflows auslösen, Datensätze erstellen oder bestehende Einträge aktualisieren.

Gesendete Daten (Request):

{
  "event": "form_submission",
  "form": {
    "id": "form_abc",
    "title": "Rückruf-Formular",
    "slug": "rueckruf-formular"
  },
  "submission": {
    "submitted_at": "2026-03-24T14:30:00Z",
    "data": {
      "bevorzugte_zeit": "Vormittags",
      "beschreibung": "Wasserhahn tropft seit 3 Tagen"
    }
  },
  "contact": {
    "id": "contact_xyz",
    "name": "Max Mustermann",
    "phone": "+491234567890",
    "email": "max@mustermann.de"
  },
  "call": {
    "id": "call_abc123",
    "topic": "Sanitär-Notfall",
    "summary": "Kunde meldet tropfenden Wasserhahn...",
    "date": "2026-03-24"
  }
}

Webhook-Variablen

Webhook-Variablen sind konfigurierbare Parameter, die zusammen mit Webhook-Anfragen gesendet werden. Sie ermöglichen die Übergabe dynamischer Daten, ohne Werte fest einzuprogrammieren.

Eigenschaften einer Variable

Statische vs. Dynamische Variablen

Wenn Sie Webhook-Variablen in Nach-dem-Anruf-Aktionen verwenden, kann jede Variable in einem von zwei Modi gesetzt werden:

• Statisch — Sie definieren einen festen Wert, der mit jeder Anfrage gesendet wird

• Dynamisch (KI-gesteuert) — Petra bestimmt den Wert automatisch anhand des Gesprächskontexts. Dabei wird KI eingesetzt, um das Gesprächsprotokoll zu analysieren und den passenden Wert zu extrahieren. Jede dynamisch aufgelöste Variable enthält eine Begründung für Transparenz.

Dynamische Variablen sind ideal für Fälle, in denen der Wert davon abhängt, was im Gespräch besprochen wurde (z.B. Art der angefragten Dienstleistung, Dringlichkeitsstufe oder Kundenkategorie).

Webhooks einrichten

Schritt 1: Webhook erstellen

1. Navigieren Sie zu Einstellungen → Webhooks

2. Klicken Sie auf „Webhook hinzufügen"

3. Füllen Sie aus:

   • Name — Ein beschreibender Name (z.B. „CRM Kundendaten abrufen")

   • URL — Ihre Endpunkt-URL

   • Typ — Wählen Sie den passenden Auslösertyp

   • Headers — Fügen Sie benutzerdefinierte HTTP-Header hinzu, falls nötig (z.B. API-Schlüssel, Authentifizierungs-Tokens)

   • Ausführungsmodus (nur bei Vor-/Nach-dem-Anruf) — Wählen Sie „Immer" oder „Bei Bedarf"

4. Speichern Sie den Webhook

Schritt 2: Variablen hinzufügen (optional)

Nach dem Erstellen des Webhooks können Sie Variablen hinzufügen:

1. Öffnen Sie den Webhook und scrollen Sie zum Variablen-Bereich

2. Klicken Sie auf „Variable hinzufügen"

3. Definieren Sie Key, Label, Ort und Typ

4. Für SELECT-Variablen konfigurieren Sie die verfügbaren Optionen

Schritt 3: Mit Aktionen oder Aufgaben verknüpfen

Für Nach-dem-Anruf-Webhooks:

1. Gehen Sie zum Aktionsbereich einer Aufgabe

2. Erstellen oder bearbeiten Sie eine Aktion vom Typ „Webhook"

3. Wählen Sie Ihren Webhook aus

4. Konfigurieren Sie die Variablenwerte (statisch oder dynamisch)

5. Legen Sie Bedingungen fest, wann die Aktion ausgeführt werden soll

Für Während-des-Anrufs-Webhooks:

1. Öffnen Sie eine Aufgabe im Aufgaben-Editor

2. Fügen Sie einen Funktionsschritt hinzu

3. Wählen Sie Ihren Während-des-Anrufs-Webhook aus

4. Die Webhook-Variablen werden zu den Parametern, die Petra während des Gesprächs erfasst

Für Vor-dem-Anruf-Webhooks: Vor-dem-Anruf-Webhooks mit dem Modus „Immer" werden automatisch ausgeführt. „Bei Bedarf"-Webhooks müssen mit einer Aktion verknüpft werden.

Webhooks testen

Sie können Webhooks direkt aus dem Dashboard testen:

1. Öffnen Sie einen Webhook unter Einstellungen → Webhooks

2. Klicken Sie auf den „Testen"-Button

3. HalloPetra sendet eine Beispielanfrage mit Testdaten an Ihre URL

4. Die Antwort wird in einer Benachrichtigung angezeigt

Dies ist nützlich, um zu überprüfen, ob Ihr Endpunkt erreichbar ist, korrekt authentifiziert und das erwartete Format zurückgibt.

Webhook-Ergebnisse einsehen

Nach einem Anruf sind die Details der Webhook-Ausführung in der Anrufdetailansicht sichtbar:

• Die Anruf-Timeline zeigt eine Webhook-Karte mit Erfolgs-/Fehlerindikatoren

• Klicken Sie auf die Karte, um vollständige Request-/Response-Details einschließlich Statuscodes, Payloads und Dauer zu sehen

• Fehlgeschlagene Webhooks können direkt aus dieser Ansicht erneut ausgelöst werden

Integration mit Automatisierungsplattformen

Webhooks funktionieren nahtlos mit gängigen Automatisierungsplattformen:

• n8n — HalloPetra bietet integrierte Unterstützung für n8n Cloud-Instanzen mit automatischer Szenario-Schlüssel-Übertragung

• Make (ehemals Integromat) — Verwenden Sie das „Custom Webhook"-Triggermodul

• Zapier — Verwenden Sie den „Webhooks by Zapier"-Trigger

• Eigene APIs — Jeder HTTP-Endpunkt, der JSON-POST-Anfragen akzeptiert

Beispiel: n8n-Workflow

1. Erstellen Sie einen „Webhook"-Triggerknoten in n8n

2. Kopieren Sie die Webhook-URL

3. Erstellen Sie einen Nach-dem-Anruf-Webhook in HalloPetra mit dieser URL

4. Bauen Sie Ihren Automatisierungs-Workflow (z.B. CRM-Eintrag erstellen → Slack-Benachrichtigung senden → Tabelle aktualisieren)

5. Verknüpfen Sie den Webhook mit einer Aufgaben-Aktion

Bedingungen & Ausführungsregeln

Webhook-Aktionen unterstützen das vollständige HalloPetra-Bedingungssystem:

Standardbedingungen:

• Zeitbasiert (Wochentag, Zeitraum, Geschäftszeiten / außerhalb der Geschäftszeiten)

• Datumsbereich (bestimmte Zeiträume)

• Kontaktgruppen-Zugehörigkeit

Anrufspezifische Bedingungen (nur Nach-dem-Anruf):

• Anrufdauer-Schwellenwerte

• Ob der Anruf weitergeleitet wurde

• Ob eine bestimmte Aufgabe ausgeführt wurde

• Ob bestimmte Daten erfasst wurden

Dies ermöglicht präzise Steuerung — zum Beispiel: „Daten nur an den CRM-Webhook senden, wenn der Anruf länger als 30 Sekunden dauerte UND die Aufgabe ‚Neukunde' ausgeführt wurde."

Technische Details

HTTP-Methode

Alle Webhooks verwenden POST-Anfragen mit Content-Type: application/json.

Timeouts

Wenn ein Webhook nicht innerhalb des Timeouts antwortet, fährt Petra normal fort. Webhook-Fehler blockieren oder unterbrechen niemals einen Anruf.

Sicherheit

• SSRF-Schutz — HalloPetra blockiert Anfragen an private/interne IP-Adressen, um Server-Side Request Forgery zu verhindern

• Benutzerdefinierte Headers — Nutzen Sie die Header-Konfiguration, um API-Schlüssel, Bearer-Tokens oder andere Authentifizierungsdaten zu übergeben

• HTTPS — Verwenden Sie für Produktions-Webhooks immer HTTPS-Endpunkte

Fehlerbehandlung

• Webhooks werden parallel ausgeführt, wenn mehrere konfiguriert sind

• Einzelne Webhook-Fehler beeinträchtigen weder andere Webhooks noch den Anrufablauf

• Alle Webhook-Ausführungen (Erfolg und Fehler) werden protokolliert und sind in der Anrufdetailansicht sichtbar

• Die Ausführung von Nach-dem-Anruf-Webhooks wird mit Status, Dauer und Fehlermeldungen nachverfolgt

Vorherige Webhook-Aufrufe

Während-des-Anrufs- und Nach-dem-Anruf-Webhooks erhalten ein previous_webhook_calls-Feld mit den Ergebnissen aller Webhooks, die bereits für denselben Anruf ausgeführt wurden. Dies ermöglicht verkettete Workflows, bei denen spätere Webhooks auf Daten früherer Webhooks zugreifen können.

Häufige Anwendungsfälle

Fehlerbehebung

Webhook wird nicht ausgelöst:

• Prüfen Sie, ob der Webhook mit einer Aktion verknüpft ist und die Bedingungen der Aktion erfüllt sind

• Überprüfen Sie, ob der Ausführungsmodus (Immer vs. Bei Bedarf) zu Ihrer Konfiguration passt

• Schauen Sie in der Anrufdetailansicht nach Fehlermeldungen

Timeout-Fehler:

• Stellen Sie sicher, dass Ihr Endpunkt innerhalb des Timeout-Limits antwortet

• Für Vor-dem-Anruf-Webhooks (2,5s): Halten Sie Ihre Logik schnell — verlagern Sie aufwändige Verarbeitung

• Erwägen Sie asynchrone Verarbeitung auf Ihrem Server und senden Sie eine schnelle Bestätigung zurück

Unerwartete Daten:

• Nutzen Sie den „Testen"-Button in den Webhook-Einstellungen, um die Verbindung zu überprüfen

• Prüfen Sie die Request-/Response-Details in der Anruf-Timeline

• Stellen Sie sicher, dass Ihr Endpunkt POST-Anfragen mit JSON-Content-Type akzeptiert

Authentifizierungsfehler:

• Überprüfen Sie, ob benutzerdefinierte Headers korrekt konfiguriert sind (API-Schlüssel, Tokens)

• Prüfen Sie, ob die CORS-/Firewall-Einstellungen Ihres Endpunkts Anfragen von HalloPetras Servern zulassen