Webhooks

Ein Webhook ist in der Webentwicklung eine Methode, um das Verhalten einer Webseite oder Webanwendung mit benutzerdefinierten Callbacks zu erweitern oder zu ändern. Diese Callbacks können von Drittnutzern und Entwicklern gepflegt, geändert und verwaltet werden, die nicht unbedingt mit der ursprünglichen Website oder Anwendung verbunden sind.

Zugriff auf Menüpunkt Webhooks

In der Navigation auf der linken Seite Konfigurationen > Integrationen und Werkzeuge> Webhooks anklicken.

Webhooks-Konfiguration

1. In der rechten oberen Ecke Konfiguration anklicken.

2. In Webhook-URLs eine URL einfügen und Hinzufügen anklicken.

3. Einen oder mehrere Ereignistypen auswählen. Die Folgenden stehen zur Wahl

   • Rechnungsereignisse

   • Abonnementereignisse

   • Kundenereignisse

4. Im Feld Benachrichtungen per E-Mail eine E-Mail-Adresse einfügen und Hinzufügen anklicken.

5. Einen Benutzernamen und ein Passwort in der Kachel Anmeldeinformationen eingeben.

6. Das Secret durch Klicken auf kopieren.

7. Den Webhook über den Status-Schalter aktivieren.

8. Speichern anklicken.

Erläuterung für ausstehende Webhooks

Manchmal bleiben Webhooks in der Warteschleife und es scheint, dass sie nicht einmal an den Server gesendet werden.

First in, first out

Alle Webhooks werden in FIFO-Reihenfolge (first in, first out) gruppiert für jeden Kunden gesendet.

Das bedeutet, dass davon ausgegangen werden kann, dass für jeden Kunden Ereignisse in der richtigen Reihenfolge erhalten werden.

Beispiel: CUSTOMER_UPDATED wird nicht vor CUSTOMER_CREATED ankommen.

Hinweis

Wenn der Dienst keinen HTTP-Code zwischen 200 und 299 zurückgibt:

• betrachten wir den Webhook als fehlgeschlagen

• werden wir die nächsten Webhooks für diesen Kunden blockieren

Überlegungen zu Webhooks

• Der Endpunkt muss innerhalb von 30 Sekunden antworten.

• Eine Antwort mit dem HTTP-Code 2XX gilt als erfolgreich. Alle anderen Antworten werden als Fehlschläge gewertet.

• Der Inhalt eines Webhooks benachrichtigt über ein Ereignis im Frisbii Payment System, die betroffenen Ressourcen und den Ereignistyp, trägt aber selbst keinen Zustand in sich. Es wird empfohlen, anschließend die API zu verwenden, um den aktualisierten Status einer Ressource zu erhalten.

• Der Endpunkt muss idempotent sein, d.h. mehrere Aufrufe desselben Webhooks mit demselben Ergebnis wie ein einziger Aufruf müssen möglich sein.

  Dies liegt daran, dass Kommunikationsfehler zu einem Szenario führen können, in dem Frisbii Payments einen Aufruf als fehlgeschlagen betrachtet, obwohl er empfangen wurde. Wir werden fehlgeschlagene Aufrufe wiederholen. Siehe unten.

• In Fehlerszenarien können Webhooks in einer anderen Reihenfolge ankommen. Daher immer die API verwenden, um den aktuellen Status einer Ressource abzurufen.

  Ein Beispiel dafür ist die Kündigung eines Abonnements mit anschließender Rücknahme der Kündigung. Der "Cancel"-Webhook könnte nach dem "Uncancel"-Webhook ankommen.

Best Practices

Frisbii Payment sendet max. 10 Webhook-Anfragen zu einem Zeitpunkt an den Server.

Eine gute Praxis ist es, Ereignisse in eine lokale Warteschlange auf der Seite auszulagern und 200 OK auf jedes zurückzugeben.

Das bedeutet, dass schnell reagiert werden kann und sich keine Ereignisse gegenseitig blockieren. Jedes Ereignis kann aus der Warteschlange verarbeitet und die Werte problemlos aktualisiert werden.