Webhooks

Ein Webhook sendet an eine URL von Ihnen, wenn im Workspace etwas passiert. Er ist das richtige Mittel für alles Ereignisgesteuerte; das Abfragen der API ist es nicht.

Legen Sie einen unter Einstellungen → Entwicklung → Webhooks an. Das braucht mindestens die Manager-Rolle.

Einrichten

Ein Webhook hat drei Teile:

Ziel-URL — wohin die Anfrage geht. Sie muss HTTPS sein und aus dem Internet erreichbar.

Ereignis — welche Änderung ihn auslöst. Ein Ereignis pro Webhook; legen Sie mehrere für mehrere Ereignisse an, oder nutzen Sie * für alle.

Geheimnis — wird für Sie erzeugt und signiert die Nutzdaten.

Ereignisse

Ereignis	Löst aus, wenn
*	Eines der Ereignisse unten
message.create	Eine Nachricht kommt an oder wird gesendet
message.update	Eine Nachricht ändert sich
message.delete	Eine Nachricht wird gelöscht
contact.create	Ein Kontakt wird angelegt
contact.update	Ein Kontakt ändert sich
contact.delete	Ein Kontakt wird gelöscht
conversation.create	Eine Konversation wird angelegt
conversation.update	Eine Konversation ändert sich
conversation.delete	Eine Konversation wird gelöscht
conversation.assign	Eine Konversation wird zugewiesen
conversation.close	Eine Konversation wird geschlossen
conversation.reopen	Eine geschlossene Konversation geht wieder auf

Signatur prüfen

Jede Anfrage wird mit dem Geheimnis des Webhooks signiert. Prüfen Sie die Signatur, bevor Sie auf Nutzdaten reagieren. Ihr Endpunkt ist eine öffentliche URL, und ohne Prüfung kann jeder, der sie findet, alles darauf senden.

Berechnen Sie den HMAC des rohen Anfragekörpers mit Ihrem Geheimnis und vergleichen Sie ihn mit dem Signatur-Header, mit einem laufzeitkonstanten Vergleich.

Antworten

Antworten Sie zügig mit 2xx. FirstReply wertet alles andere als Fehlschlag und versucht es mit Wartezeit erneut.

Erledigen Sie die eigentliche Arbeit asynchron: Anfrage bestätigen, Nutzdaten in eine Queue legen und nach dem Antworten verarbeiten. Ein Webhook-Handler, der vor dem Antworten drei andere Dienste aufruft, läuft irgendwann in ein Timeout und erzeugt Dubletten.

Behandeln Sie Dubletten. Wiederholungen bedeuten, dass ein Ereignis mehr als einmal ankommen kann. Machen Sie Ihren Handler idempotent, anhand der Ereignis-ID.

Was damit gebaut wird

Kontakte anreichern. Bei contact.create die Person in Ihrem System nachschlagen und Kundennummer und Tarif als eigene Felder zurückschreiben.

Anderswo benachrichtigen. Bei conversation.create mit hoher Priorität in einen Slack-Kanal posten.

Status abgleichen. Bei conversation.close das entsprechende Ticket in dem System schließen, das Ihre Firma sonst noch betreibt.

Messen. Bei jedem Ereignis in Ihr eigenes Data Warehouse schreiben, für Auswertungen, die über Kennzahlen hinausgehen.

Fehlersuche

Es kommt nichts an. Prüfen Sie, dass die URL von außerhalb Ihres Netzes erreichbar ist, HTTPS mit gültigem Zertifikat nutzt, und dass der Webhook aktiv ist.

Nur manche Ereignisse kommen an. Jeder Webhook trägt ein Ereignis. conversation.close löst bei einer neuen Konversation nicht aus; nutzen Sie *, wenn Sie alles wollen.

Alles kommt doppelt an. Ihr Endpunkt antwortet nicht schnell genug mit 2xx und die Wiederholung trifft ein. Erst bestätigen, dann arbeiten.