Webhooks: Andere Tools informieren, was passiert ist

#Was ein Webhook ist

Stellen Sie es sich so vor: Ihr Projekt ruft einen anderen Dienst an und sagt, was gerade passiert ist. Sie geben Briks eine Adresse (eine URL, die Ihnen das andere Tool genannt hat), wählen die Ereignisse, von denen es erfahren soll, und jedes Mal, wenn eines eintritt, sendet Briks eine Nachricht dorthin. Viele Automatisierungstools, Kundenlisten-Tools und Tabellen-Add-ons können Ihnen eine solche Adresse geben.

Technisch gesehen ist jede Nachricht eine POST-Anfrage: ein Aufruf mit einem Inhalt, hier in JSON geschrieben, einem einfachen Textformat, das Programme lesen können. Das empfangende Werkzeug liest den Inhalt und tut, was Sie eingerichtet haben.

record.changed folgt Änderungen, die im Studio gemacht werden: ein Datensatz, der im Tab Database hinzugefügt, bearbeitet oder gelöscht wird, eine geleerte Sammlung oder eine wiederhergestellte Datenbank. Datensätze, die die Live-Website selbst speichert, etwa eine Buchungsanfrage, die ein Besucher sendet, lösen es nicht aus.

form.received wird für Einträge aus der Vorschau ebenso gesendet wie für Einträge aus der Produktion. Jede Nachricht gibt an, woher der Eintrag stammt, sodass das andere Tool Einträge aus der Vorschau überspringen kann.

#Grenzen in jedem Plan

Sind die Aufrufe des Tages aufgebraucht, wird eine Zustellung nicht gesendet und mit Failed markiert, dazu der Hinweis: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

Sobald ein Projekt so viele Webhooks hat, wie sein Plan erlaubt, ist Add webhook ausgegraut, und ein Link Get more neben der Anzahl öffnet das Upgrade-Fenster, das den kleinsten Plan nennt, der Platz für einen weiteren hat.

#Webhook hinzufügen

Jeder Webhook in der Liste zeigt seine Adresse, Notiz und Ereignisse, mit welchem Secret er signiert ist (die ersten Zeichen) und wie die letzte Zustellung verlief. Sein Schalter stellt ihn auf On oder Off, und hinter den drei Punkten finden Sie Send a test event (bis zu zehn pro Stunde, nur solange er eingeschaltet ist), Change, New signing secret und Delete.

#So sieht eine Lieferung aus

Jede Zustellung hat dieselben drei Teile: type (der Code des Ereignisses), timestamp (wann es geschah, in UTC) und data (die Details). Hier ein Formulareintrag:

Jede Zustellung enthält außerdem drei Header: webhook-id (die ID der Nachricht), webhook-timestamp (wann sie gesendet wurde, in Sekunden) und webhook-signature. Sie folgen dem offenen Standard-Webhooks-Format, sodass Tools, die es verstehen, Zustellungen für Sie prüfen können.

#Prüfen, ob eine Zustellung echt ist

Jeder kann eine Nachricht an eine Adresse senden, deshalb sollte die empfangende Seite die Signatur prüfen, bevor sie einer Nachricht traut. Die Signatur wird mit dem Signing Secret erstellt, das nur Sie und Briks kennen. Sobald ein Projekt einen Webhook hat, zeigt die Seite Webhooks unter Checking a delivery is genuine ein kurzes Codebeispiel. In Worten läuft die Prüfung so ab:

1. Nehmen Sie den Body genau so, wie er angekommen ist, als Text, bevor Sie ihn als JSON lesen.
2. Verbinden Sie webhook-id, webhook-timestamp und den Body mit Punkten dazwischen.
3. Nehmen Sie Ihr Secret, entfernen Sie das whsec_ am Anfang und dekodieren Sie den Rest aus Base64. Das ist der Schlüssel.
4. Signieren Sie den zusammengefügten Text mit HMAC SHA-256 und diesem Schlüssel, schreiben Sie das Ergebnis in Base64 und setzen Sie v1, davor.
5. Die Zustellung ist echt, wenn das mit einem der durch Leerzeichen getrennten Werte in webhook-signature übereinstimmt und der Zeitstempel höchstens fünf Minuten von jetzt abweicht.

Eine Zustellung, die erneut versucht wird, behält ihre webhook-id, sodass der Empfänger die bereits verarbeiteten IDs speichern und Wiederholungen überspringen kann.

#Zustellungen und Wiederholungen

Deliveries listet jede Zustellung der letzten dreißig Tage auf, die neueste zuerst. Grenzen Sie die Liste mit Status ein und klicken Sie auf Show. Mit einem Klick auf einen Eintrag sehen Sie die vollständige Nachricht, einen etwaigen Fehler und die Antwort der Adresse.

Jeder Versuch wartet bis zu 15 Sekunden auf eine Antwort. Ist die Antwort kein 2xx, versucht Briks es erneut: insgesamt fünf Versuche, der erste sofort und die weiteren nach etwa 30 Sekunden, 2 Minuten, 8 Minuten und 32 Minuten, also grob 45 Minuten vom ersten bis zum letzten. Die Antwort 410 (gone) beendet die Wiederholungen sofort. Weiterleitungen werden nicht verfolgt, geben Sie also die endgültige Adresse an.

Sobald eine Zustellung Failed oder Delivered ist, sendet Send again dieselbe Nachricht mit derselben ID erneut, neu signiert. Der Webhook muss aktiviert sein.

#Einblicke und Einstellungen

Insights fasst die letzten dreißig Tage zusammen: Deliveries, den Anteil Delivered, Failed after every try (mit der Zahl der nötigen Wiederholungen) und die Average answer-Zeit. Darunter zeigen By event und By address, wo sich Fehler häufen.

Settings enthält unter Download the webhooks den Eintrag Download JSON mit Adresse, Ereignissen und Notiz jedes Webhooks. Signaturgeheimnisse sind nie enthalten. Der Gefahrenbereich enthält Clear log, das das Zustellprotokoll löscht und alle Wiederholungen stoppt, und Delete all, das jeden Webhook entfernt, nachdem Sie den Namen des Projekts eingegeben haben. Beides ist Owners und Admins vorbehalten.

#Praxisbeispiel: Formulareinträge in ein anderes Tool übertragen

Formulareinträge lassen sich nicht aus dem Studio exportieren. Mit einem Webhook behalten Sie sie also in einem anderen Tool, sobald sie eintreffen. Das Studio speichert sie ebenfalls: Die letzten 100 erscheinen unter Settings, Forms.