Webhooks

Aktualisiert am

Wo: Einstellungen > Integrationen > Webhooks

Wofür es gedacht ist:

"Eingehende Ereignisse an Ihren eigenen Server weiterleiten." SyBox sendet eine Kopie ausgewählter WhatsApp-Ereignisse in Echtzeit an eine URL Ihres Servers. Webhooks unterstützen ausschließlich WhatsApp-Nummern. Messenger, Instagram, Telegram, E-Mail und SMS werden nicht übertragen.

Wer Zugriff hat: der Hauptadministrator und Teammitglieder mit der Berechtigung "WhatsApp-Nummern verwalten". Um einen Webhook zu erstellen oder einen pausierten wieder zu aktivieren, ist zusätzlich die Berechtigung "Kontaktnummer anzeigen" nötig, da die Kopien die echten Telefonnummern der Kunden enthalten.

Verfügbare Ereignisse:

  • "Eingehende Nachricht": Ein Kunde hat eine Nachricht geschickt.
  • "Nachrichtenstatus": Eine von Ihnen gesendete Nachricht wurde übermittelt, zugestellt, gelesen oder ist fehlgeschlagen.
  • "Reaktion": Ein Kunde hat auf eine Nachricht reagiert.
  • "Sprachtranskription" (Zusatzoption): Eine Sprachnotiz wird kurzzeitig (bis zu ca. zwei Minuten) zurückgehalten, damit der transkribierte Text direkt mitgesendet werden kann. Standardmäßig deaktiviert.

So fügen Sie einen Webhook hinzu

  1. Gehen Sie zu Einstellungen > Integrationen > Webhooks.
    Settings, Webhooks: an active webhook with its last result, and the "Add webhook" button
  2. Klicken Sie auf "Webhook hinzufügen".
    The new webhook window: its name and the address it calls
  3. Geben Sie einen "Namen" ein.
  4. Tragen Sie die "Ziel-URL" ein. Es muss "Eine öffentliche https-Adresse, die wir erreichen können" sein. Reine http-Adressen sowie private oder interne Netzwerkadressen werden abgelehnt.
  5. Aktivieren Sie unter "Ereignisse" mindestens ein Ereignis. "Eingehende Nachricht" ist standardmäßig aktiv.
  6. Optional: Aktivieren Sie "Sprachtranskription", um Sprachnotizen inklusive Textfassung zu empfangen.
  7. Lassen Sie unter "Nummern" die Option "Alle Nummern" aktiviert, um sämtliche WhatsApp-Nummern abzudecken. Deaktivieren Sie sie, um gezielt einzelne Nummern auszuwählen.
  8. Klicken Sie auf Speichern.
  9. Ein Fenster zeigt den "Signaturschlüssel". "Jetzt kopieren — wird nur einmal angezeigt". Speichern Sie ihn auf Ihrem Server.

Details zur Zustellung:

  • Jede Zustellung verwendet dasselbe Format wie die nativen WhatsApp-Webhooks von Meta.
  • Jede Zustellung wird mit Ihrem Signaturschlüssel auf dieselbe Weise signiert, wie Meta Webhooks signiert. Wenn Ihr Server bereits Metas Webhooks prüft, kann er die von SyBox mit Ihrem SyBox-Schlüssel validieren.
  • Antwortet Ihr Server nicht erfolgreich, unternimmt SyBox über etwa eine Stunde hinweg mehrere Versuche mit stetig wachsenden Abständen. Danach wird das Ereignis verworfen.
  • Dasselbe Ereignis kann gelegentlich doppelt eingehen, etwa nach einem Timeout. Ihr Server sollte Duplikate abfangen können.

So testen Sie einen Webhook

  • SyBox bietet keine Test-Schaltfläche für Webhooks. Gehen Sie zum Testen so vor:
  • Stellen Sie sicher, dass der Webhook aktiv ist und die gewünschte Nummer abdeckt.
  • Senden Sie von einem anderen Smartphone eine WhatsApp-Nachricht an diese Nummer.
    To test a webhook: "HTTP 200" marked on the screen in SyBox
  • Wechseln Sie zurück zu Einstellungen > Integrationen > Webhooks. Die Karte zeigt die letzte Antwort Ihres Servers samt Zeitstempel. Ein erfolgreicher Status (z. B. "HTTP 200") erscheint grün, Fehler erscheinen rot. "Letzte Zustellung: nie" bedeutet, dass noch keine Übertragung stattfand.

So bearbeiten, pausieren oder löschen Sie einen Webhook

  1. Klicken Sie auf Bearbeiten, um Name, Adresse, Ereignisse oder Nummern anzupassen.
    To edit, pause or delete a webhook: "Edit" marked on the screen in SyBox
  2. Um den Signaturschlüssel zu erneuern, tragen Sie einen neuen unter "Signaturschlüssel" ein. Lassen Sie das Feld leer, um den bestehenden beizubehalten ("Leer lassen, um den aktuellen Schlüssel zu behalten").
  3. Klicken Sie auf Aktivieren / Deaktivieren, um ihn zu pausieren. Ereignisse, die währenddessen eingehen, werden zwischengespeichert und bei baldiger Reaktivierung nachgeliefert.
  4. Klicken Sie auf Löschen und bestätigen Sie mit "Diesen Webhook löschen?".

Bedingungen und Hinweismeldungen:

  • Name und Ziel-URL sind Pflichtfelder, und mindestens ein Ereignis muss gewählt sein. Andernfalls erscheint "Unvollständige Daten".
  • Adressen ohne öffentliches https werden mit "Eine öffentliche https-Adresse, die wir erreichen können" abgelehnt.
Ich habe den Signaturschlüssel verloren.

Er kann nicht erneut angezeigt werden. Bearbeiten Sie den Webhook, tragen Sie bei "Signaturschlüssel" einen neuen eigenen Schlüssel ein, speichern Sie und hinterlegen Sie diesen auf Ihrem Server.

Mein Webhook empfängt keinerlei Daten.

Prüfen Sie folgende vier Punkte: (1) Der Webhook ist aktiviert. (2) Mindestens ein Ereignis ist ausgewählt. (3) Die richtige WhatsApp-Nummer oder "Alle Nummern" ist zugewiesen. (4) Es ist überhaupt eine WhatsApp-Nummer im Arbeitsbereich angebunden, da Webhooks nur WhatsApp-Events weiterleiten. Prüfen Sie anschließend das Ergebnis der letzten Zustellung auf der Karte.

Die Karte zeigt einen roten Fehler wie HTTP 404 oder 500.

SyBox konnte Ihre Adresse erreichen, Ihr Server hat jedoch einen Fehler zurückgegeben. Prüfen Sie die URL und die Server-Logs.

Ich kann keinen Webhook anlegen — angeblich fehle mir die Berechtigung.

Das Anlegen oder Reaktivieren eines Webhooks erfordert sowohl "WhatsApp-Nummern verwalten" als auch "Kontaktnummer anzeigen". Wenden Sie sich an Ihren Administrator.