Webhooks
Aktualisiert am
Wo: Einstellungen > Integrationen > Webhooks
Wozu es dient:
„Eingehende Ereignisse an Ihren eigenen Server weiterleiten.“ SyBox leitet eine Kopie jedes ausgewählten Ereignisses in Echtzeit an eine Adresse auf Ihrem Server weiter. WhatsApp-Ereignisse kommen im Meta-eigenen Format an. Kundennachrichten auf Messenger, Instagram, Telegram, TikTok und im Live-Chat sowie die Unterhaltungsereignisse (Erledigt, Labels, Kontakte, Deals, CRM-Fälle) kommen im SyBox-eigenen Format an. E-Mail- und SMS-Nachrichten werden nicht übertragen.
Wer Zugriff hat: Der Hauptadministrator sowie Teammitglieder mit der Berechtigung „Kanäle verwalten“. Um einen Webhook zu erstellen oder einen pausierten wieder zu aktivieren, benötigen Sie zusätzlich die Berechtigung „Kontaktnummer anzeigen“, da die Weiterleitungen die echten Rufnummern der Kunden enthalten.
Auswählbare Ereignisse:
- „Eingehende Nachricht“: Ein Kunde hat eine Nachricht gesendet.
- „Nachrichtenstatus“: Eine von Ihnen gesendete Nachricht wurde gesendet, zugestellt, gelesen oder ist fehlgeschlagen.
- „Reaktion“: Ein Kunde hat auf eine Nachricht reagiert.
- „Unterhaltung als erledigt markiert“: Eine Unterhaltung wurde als erledigt markiert – durch ein Teammitglied, durch eine Automatisierung oder automatisch nach Stille des Kunden.
- „Label hinzugefügt oder entfernt“: Ein Label wurde zu einer Unterhaltung hinzugefügt oder von ihr entfernt.
- „Kontakt erstellt oder aktualisiert“: Ein neuer Kontakt wurde angelegt oder Name, E-Mail-Adresse oder Kontaktfelder eines Kontakts wurden geändert. Ein Kontaktimport löst diese Ereignisse nicht aus.
- „Deal abgeschlossen“: In einer Unterhaltung wurde ein Deal erfasst.
- „CRM-Fall geöffnet oder geschlossen“: Ein CRM-Fall wurde geöffnet oder als gelöst, nicht gelöst oder storniert geschlossen. Da ein Fall zu keiner Nummer gehört, erhält ihn nur ein Webhook, der alle Nummern abdeckt, nicht einer, der auf bestimmte Nummern beschränkt ist.
Die letzten fünf kommen für jeden Kanal im SyBox-eigenen Format an. Die Seite „Entwicklerdokumentation“ zeigt für jedes Ereignis ein Beispiel.
- „Sprachtranskription“ (zusätzliche Option): Eine Sprachnachricht wird kurz zurückgehalten (bis zu etwa zwei Minuten), damit der transkribierte Text direkt mitgesendet werden kann. Diese Option ist standardmäßig inaktiv.
- Gehen Sie zu Einstellungen > Integrationen > Webhooks.
- Klicken Sie auf „Webhook hinzufügen“.
- Vergeben Sie einen Namen.
- Tragen Sie die „Ziel-URL“ ein. Es muss „Eine öffentliche https-Adresse, die wir erreichen können“ sein. Reine HTTP-Adressen sowie Adressen aus privaten oder internen Netzwerken werden abgewiesen.
- Aktivieren Sie unter „Ereignisse“ mindestens ein Ereignis. „Eingehende Nachricht“ ist standardmäßig vorausgewählt.
- Optional: Aktivieren Sie „Sprachtranskription“, um Sprachnachrichten inklusive Text zu erhalten.
- Belassen Sie unter „Nummern“ die Auswahl auf „Alle Nummern“, um sämtliche WhatsApp-Nummern einzuschließen, oder deaktivieren Sie die Option und wählen Sie gezielt einzelne Nummern aus.
- Klicken Sie auf Speichern.
- Ein Fenster zeigt den „Signaturschlüssel“. „Jetzt kopieren — wird nur einmal angezeigt.“ Hinterlegen Sie ihn auf Ihrem Server.
Hinweise zur Zustellung:
- Jede Zustellung verwendet dasselbe Format wie Metas eigene WhatsApp-Webhooks.
- Jede Sendung wird mit Ihrem Signaturschlüssel auf die gleiche Weise signiert, wie Meta seine Webhooks signiert. Wenn Ihr Server Metas Webhooks bereits verifiziert, kann er SyBox-Aufrufe mit dem SyBox-Schlüssel auf dieselbe Art prüfen.
- Antwortet Ihr Server nicht erfolgreich, versucht SyBox die Zustellung mehrfach mit größer werdenden Abständen über einen Zeitraum von etwa einer Stunde. Danach wird der Zustellversuch für dieses Ereignis abgebrochen.
- Dasselbe Ereignis kann gelegentlich doppelt zugestellt werden, etwa nach einem Timeout. Ihr Server sollte Duplikate abfangen können.
- Stellen Sie sicher, dass der Webhook eingeschaltet ist. Ist er ausgeschaltet, sehen Sie „Schalten Sie diesen Webhook zuerst ein.“
- Klicken Sie auf seiner Kachel auf „Testereignis senden“. Sie sehen „Ein Testereignis wird gesendet. Das Ergebnis erscheint unter Zustellungen.“
- Wenige Sekunden später öffnet sich die Liste „Zustellungen“ und zeigt die Antwort Ihres Servers. Die Kachel zeigt außerdem die letzte Antwort Ihres Servers samt Zeitstempel. Eine erfolgreiche Antwort (z. B. „HTTP 200“) wird grün dargestellt, ein Fehler rot. „Letzte Zustellung: nie“ bedeutet, dass bisher noch nichts übertragen wurde.
Ein Testereignis enthält „event“: „test“ und überträgt keine Kundendaten. Sie können alle paar Sekunden eines senden; versuchen Sie es früher, sehen Sie „Vor einem Moment wurde bereits ein Test gesendet. Versuchen Sie es in wenigen Sekunden erneut.“
- Klicken Sie auf der Kachel des Webhooks auf „Zustellungen“.
- Die Liste zeigt „Die letzten 50 Zustellungen der vergangenen 7 Tage.“, die neuesten zuerst. Jede zeigt ihr Ereignis, wann der Versuch stattfand und ihren Status:
- „Zugestellt“: Ihr Server hat erfolgreich geantwortet.
- „Wartet auf Versand“: Es wurde noch kein Versuch unternommen.
- „Fehlgeschlagen, neuer Versuch läuft“: Ihr Server hat nicht erfolgreich geantwortet, und SyBox versucht es später erneut.
- „Nicht zugestellt“: SyBox hat die Versuche eingestellt.
- Außerdem werden der HTTP-Code, mit dem Ihr Server geantwortet hat, die Dauer der Antwort in Millisekunden sowie „Versuche: [Anzahl]“ angezeigt, wenn mehr als ein Versuch unternommen wurde. Die Nachricht selbst wird nicht angezeigt.
- Um eine Zustellung erneut zu senden, klicken Sie bei einem Eintrag mit dem Status „Zugestellt“ oder „Nicht zugestellt“ auf „Erneut senden“. Sie sehen „Für den erneuten Versand eingereiht.“ Das erneute Senden erfordert die Berechtigung „Kontaktnummer anzeigen“, da hierbei erneut Kundendaten gesendet werden.
Automatisch ausgeschaltet:
Wenn Ihr Server dauerhaft fehlschlägt – 20 Versuche in Folge über mehr als eine Stunde hinweg –, schaltet SyBox den Webhook aus. Auf der Kachel erscheint in Rot „Automatisch ausgeschaltet nach [Anzahl] fehlgeschlagenen Zustellungen in Folge“, und der Haupt-Admin erhält die Benachrichtigung „Ein Webhook wurde ausgeschaltet“. Seine wartenden Ereignisse werden 24 Stunden lang aufbewahrt. Korrigieren Sie die Adresse oder Ihren Server und schalten Sie den Webhook dann wieder ein: Die wartenden Ereignisse werden gesendet und der Zähler beginnt wieder bei null.
- Klicken Sie auf Bearbeiten, um Name, Adresse, Ereignisse oder Nummern anzupassen.
- Um den Signaturschlüssel zu erneuern, tragen Sie einen neuen Wert unter „Signaturschlüssel“ ein. Lassen Sie das Feld leer, um den aktuellen Schlüssel beizubehalten („Leer lassen, um den aktuellen Schlüssel zu behalten“).
- Klicken Sie auf Aktivieren / Deaktivieren, um den Webhook zu pausieren. Ereignisse, die währenddessen eingehen, werden zwischengespeichert. Schalten Sie ihn zeitnah wieder ein, werden sie nachgeliefert.
- Klicken Sie auf Löschen und bestätigen Sie mit „Diesen Webhook löschen?“.
Regeln und Hinweise:
- Name und Ziel-URL sind Pflichtangaben, und mindestens ein Ereignis muss aktiv sein. Andernfalls erscheint „Unvollständige Daten“.
- Eine Adresse, die nicht über öffentliches HTTPS erreichbar ist, wird mit dem Hinweis „Eine öffentliche https-Adresse, die wir erreichen können“ abgewiesen.
Ich habe den Signaturschlüssel verloren.
Er kann nicht erneut angezeigt werden. Bearbeiten Sie den Webhook, tragen Sie unter „Signaturschlüssel“ einen neuen Schlüssel Ihrer Wahl ein, speichern Sie und hinterlegen Sie diesen neuen Schlüssel auf Ihrem Server.
Mein Webhook wurde ausgeschaltet, obwohl ich das nicht getan habe.
SyBox hat ihn ausgeschaltet, nachdem Ihr Server über mehr als eine Stunde hinweg 20-mal in Folge fehlgeschlagen ist. Siehe „Automatisch ausgeschaltet“ oben: Reparieren Sie Ihren Server und schalten Sie den Webhook innerhalb von 24 Stunden wieder ein, damit die wartenden Ereignisse gesendet werden.
Mein Webhook empfängt keinerlei Daten.
Klicken Sie auf seiner Kachel zuerst auf „Testereignis senden“ und schauen Sie unter „Zustellungen“ nach. Prüfen Sie dann folgende vier Punkte: (1) Ist der Webhook aktiviert? (2) Ist mindestens ein Ereignis ausgewählt? (3) Deckt er die richtige WhatsApp-Nummer bzw. „Alle Nummern“ ab? (4) Kam die Nachricht über einen Kanal, den Webhooks übertragen (WhatsApp, Messenger, Instagram, Telegram, TikTok oder Live-Chat; nicht E-Mail oder SMS)? Werfen Sie anschließend einen Blick auf das letzte Zustellergebnis auf der Kachel.
Die Kachel zeigt einen roten Fehler wie HTTP 404 oder 500.
SyBox konnte Ihre Adresse erreichen, aber Ihr Server hat einen Fehler zurückgemeldet. Prüfen Sie die URL und die Server-Logs.
Ich kann keinen Webhook anlegen. Mir wird angezeigt, dass mir die Berechtigung fehlt.
Zum Erstellen oder Reaktivieren eines Webhooks sind sowohl „Kanäle verwalten“ als auch „Kontaktnummer anzeigen“ erforderlich. Wenden Sie sich an Ihren Administrator.