Webhooks

Ein Webhook ist in der Webentwicklung eine Methode, um das Verhalten einer Webseite oder Webanwendung mit benutzerdefinierten Rückrufen zu erweitern oder zu ändern. Diese Rückrufe 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 das Webhooks Interface

Zunächst werden wir Sie auf die richtige Seite begleiten.

• Klicken Sie auf Konfigurationen > Integrationen und Tools > Webhooks, um über die Navigation auf der linken Seite auf die Seite Webhooks zu gelangen.
  

Webhooks-Konfiguration

1. Klicken Sie auf in der oberen rechten Ecke.

2. Fügen Sie unter Webhook urls eine URL hinzu und klicken Sie auf .

3. Wählen Sie einen oder mehrere Ereignistypen aus, Sie haben die Wahl zwischen

   • Rechnungsereignisse

   • Abonnementereignisse

   • Kundenereignisse

4. Fügen Sie eine E-Mail-Adresse in das Feld " Warn-E-Mails " ein und klicken Sie auf .

5. Geben Sie einen Benutzernamen und ein Passwort in das Feld Anmeldeinformationen ein.

6. Sie können den geheimen Schlüssel kopieren, indem Sie auf klicken.

7. Aktivieren Sie den Webhaken mit dem Schalter .

8. Klicken Sie auf .

Erklärung für ausstehende Webhooks

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

Inhalt:

• Grund für ausstehende Webhooks

• Erwägungen für Webhooks

• Best Practices

First in, first out

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

Das bedeutet, dass Sie davon ausgehen können, dass Sie für jeden Kunden Ereignisse in der richtigen Reihenfolge erhalten.

Beispiel: Sie erhalten CUSTOMER_UPDATED nicht vor CUSTOMER_CREATED.

Hinweis

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

• betrachten wir den Webhook als fehlgeschlagen

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

Erwägungen für Webhooks

• Ihr 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 informiert über ein Ereignis im Billwerk+ Payment System, die betroffenen Ressourcen und den Ereignistyp, trägt aber selbst keinen Status. Es wird empfohlen, anschließend die API zu verwenden, um den aktualisierten Status einer Ressource zu erhalten.

• Ihr Endpunkt muss idempotent sein, d.h. mehrere Aufrufe desselben Web-Hooks mit demselben Ergebnis wie ein einziger Aufruf sind möglich.

  Dies liegt daran, dass Kommunikationsfehler dazu führen können, dass Billwerk+ Zahlungsverkehr einen Aufruf als gescheitert ansieht, obwohl er empfangen wurde. Wir werden fehlgeschlagene Aufrufe wiederholen. Siehe unten.

• In Fehlerszenarien können Webhooks außer der Reihe geliefert werden. Verwenden Sie daher immer die API, um den aktuellen Zustand einer Ressource zu ermitteln.

  Ein Beispiel ist die Kündigung eines Abonnements, gefolgt von einer Rücknahme der Kündigung. Der Webhaken zum Abbrechen könnte nach dem Aufheben des Abbruchs empfangen werden.

Best Practices

Billwerk+ Payment schickt maximal 10 Webhook-Anfragen gleichzeitig an Ihren Server.

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

Das bedeutet, dass Sie schnell reagieren können und sich keine Ereignisse gegenseitig blockieren. Sie können dann jedes Ereignis aus Ihrer Warteschlange verarbeiten und Ihre Anlagen problemlos aktualisieren.