Mithilfe von Events können Sie Echtzeitbenachrichtigungen von GoCardless erhalten, wenn bestimmte Vorgänge in Ihrem Konto stattfinden, damit Sie darauf mit einer automatisierten Aktion reagieren können, zum Beispiel:
- Wenn eine Zahlung aufgrund eines nicht gedeckten Kontos fehlschlägt, die Zahlung automatisch wiederholen
- Wenn ein Kunde sein Lastschriftmandat bei der Bank storniert, sein Konto vorübergehend sperren
- Wenn der Dauerauftrag eines Kunden eine neue Zahlung erzeugt, diese Zahlung für das Konto aufzeichnen
Sie können Event-Informationen mit zwei Methoden erhalten:
Webhooks - Ein Webhook ist eine Anforderung, die GoCardless an Ihren Server sendet, um Sie über ein Event zu benachrichtigen.
Der Endpunkt „Events“ - Sie können Events direkt am Endpunkt „Events“ auflisten, wenn Sie die Daten lieber selbst abrufen möchten. Dies empfiehlt sich beispielsweise, wenn eine große Anzahl von Events verarbeitet werden muss.
Verarbeiten von Events mithilfe von Webhooks
Localhost mithilfe von ngrok für das Internet zugänglich machen
Wenn Sie mit Webhooks experimentieren möchten, muss Ihr Code über das Internet zugänglich sein, damit er für die HTTP-Anforderungen von GoCardless erreichbar ist. Wenn Sie mit lokalen Verzeichnissen arbeiten, geht dies am einfachsten mit ngrok.
Laden Sie das Tool herunter und befolgen Sie die auf der Seite angezeigten Installationsanweisungen. (Sie müssen das Archiv entpacken und die ngrok-Binärdatei in Ihrem PATH verfügbar machen).
Nun führen Sie einfach ngrok http <Port>
aus, wobei <Port> der Port ist, auf dem Ihr Webserver läuft (z. B. ngrok http 8000
, wenn der Server auf Port 8000 läuft).
Es werden zwei Links angezeigt, die zu localhost:8000 weiterleiten. Wählen Sie die URL aus, die mit https beginnt, und kopieren Sie sie in die Zwischenablage.
In der Sandbox können Sie eine HTTP-URL für Ihre Webhooks verwenden, in der Live-Umgebung muss der Endpunkt jedoch mit HTTPS gesichert werden.
Hinzufügen einer Webhook-URL im GoCardless-Dashboard
Um Webhooks empfangen zu können, müssen Sie über Ihr Dashboard hier einen Webhook-Endpunkt hinzufügen.
Geben Sie einfach die HTTPS-URL von vorhin ein und fügen Sie den Pfad hinzu, an dem Ihr Webhook-Handler verfügbar sein wird. Geben Sie dem Endpunkt einen Namen und klicken Sie dann auf „Webhook-Endpunkt erstellen“. Klicken Sie nun auf Ihren neuen Endpunkt in der Liste und kopieren Sie das Kennwort in die Zwischenablage.
Erstellen eines Webhook-Handlers
Webhooks sind HTTP-POST-Anforderungen mit Text im JSON-Format, die an die von Ihnen angegebene URL gesendet werden.
Der erste Schritt nach dem Empfang eines Webhooks ist die Überprüfung seiner Signatur. Damit stellen Sie sicher, dass er wirklich von GoCardless stammt und nicht gefälscht ist. Die Signatur befindet sich im Webhook-Signatur-Header der Anforderung. Nun muss nur noch die Signatur mithilfe des per POST gesendeten JSON-Codes und des Passworts des Webhook-Endpunkts (das zuvor kopiert wurde) berechnet und mit der Signatur im Header verglichen werden.
Wenn Sie übereinstimmen, ist der Webhook echt, da nur Ihnen und GoCardless das Kennwort bekannt ist. Sie müssen das Kennwort unbedingt geheim halten und regelmäßig im Dashboard ändern.
Nachdem die Signatur authentifiziert wurde, können Sie eine 2xx-Antwort senden, bevor die JSON-Nutzlast verarbeitet wird.
Hinweis: Wenn Sie nicht innerhalb von 10 Sekunden mit einer 2xx-Antwort reagieren, schlägt der Webhook fehl und wird dann in den hier angegebenen Abständen wiederholt. Die Webhooks sollten daher unbedingt asynchron verarbeitet werden, damit es beim gleichzeitigen Empfang einer großen Anzahl von Events nicht zu Zeitüberschreitungen kommt. Sie sollten die 2xx-Antwort also vor der Verarbeitung des Webhooks senden.
Nachdem die für ein Event gewünschten Aktionen ausgeführt wurden, empfiehlt es sich, diese aufzuzeichnen, damit das Event nicht versehentlich zweimal verarbeitet wird.
Ausführliche Codebeispiele zum Überprüfen der Signatur finden Sie hier.
Testen Ihres Webhook-Handlers
Dank der im Dashboard verfügbaren Funktion „Test-Webhook senden“ können Sie ganz einfach mit Webhooks experimentieren.
Wählen Sie den zuvor erstellten Webhook-Endpunkt aus und setzen Sie den Ressourcentyp auf mandates und die Aktion auf cancelled. Die Ursache und das Event können Sie nach Wunsch festlegen. Klicken Sie anschließend auf „Test-Webhook senden“.
Aktualisieren Sie nun die Seite. Der Webhook erscheint in der Regel sofort, möglicherweise müssen Sie die Seite jedoch mehrfach aktualisieren. Wir senden eine Anforderung an Ihren Endpunkt und Ihr Webhook erscheint dann in der Liste. Klicken Sie nun darauf. Wenn alles funktioniert, wird der Antwortcode 200 OK angezeigt.
Wiederholung / Fehlschlagen von Webhooks
Das Senden eines Webhooks kann aus verschiedenen Gründen fehlschlagen, z. B.:
- Zeitüberschreitung: Wir haben innerhalb von 10 Sekunden nach dem Senden des Webhooks keine 2xx-Antwort erhalten.
- Nicht autorisierter Zugriff: Eine Server-Autorisierung ist erforderlich, es wurde jedoch eine ungültige Autorisierung bereitgestellt.
- Die Anforderung wurde umgeleitet: Wir folgen HTTP-Umleitungen nicht und behandeln diese daher als fehlgeschlagene Webhooks.
Wenn ein Webhook fehlschlägt, wiederholen wir ihn bis zu 8 Mal in ansteigenden Abständen, d. h. nach 1 Minute, 2 Minuten, 10 Minuten usw.
Verarbeiten der Events in Webhooks
Ein Webhook kann mehrere Events enthalten. Jedes Event verfügt über einen resource_type (gibt an, für welche Art von Ressource dieses Event ausgelegt ist, z. B. „payments“ oder „mandates“), eine action (gibt an, was mit der Ressource durchgeführt wurde, z. B. die Aktion cancelled für ein Lastschriftmandat) und details (geben an, warum das Event eingetreten ist).
Eine vollständige Liste der möglichen Kombinationen finden Sie in den Referenzdokumenten und ein Beispiel für einen Event-Handler ist hier verfügbar.
Sie können Unterstützung für eine beliebige Anzahl verschiedener source_types
und Aktionen hinzufügen und alle sonstigen Daten nutzen, die wir Ihnen mit Events bereitstellen.
Auslösen von Webhooks
Bei der Entwicklung Ihrer Integration ist es hilfreich, realistische Webhooks zu empfangen, um testen zu können, wie Ihre Integration darauf reagiert.
Sie können Webhooks mit unseren Szenario-Simulatoren oder mit dem Tool „Test-Webhook senden“ auslösen: Klicken Sie dafür einfach auf der Seite „Entwickler“ im Dashboard auf „Test-Webhook senden“.
Bevor Sie das Tool „Test-Webhook senden“ verwenden können, müssen Sie zunächst einen Webhook-Endpunkt einrichten. Klicken Sie auf der Seite „Entwickler“ im Dashboard auf „Erstellen“ und dann auf „Webhook-Endpunkte“. Wenn Sie Apps erstellt haben, sind deren Webhook-Endpunkte ebenfalls verfügbar.
Anschließend können Sie den Webhook anpassen. Wählen Sie zunächst die Webhook-Endpunkte aus und legen Sie dann den Ressourcentyp, die Aktion, die Ursache, die Event-Details und das zugeordnete Kennzeichen fest.
In Ihrem Code verwenden Sie das Kennzeichen vermutlich zum Auffinden von Datensätzen in Ihrer Datenbank und zur Durchführung der für den Webhook relevanten Aktionen.
Klicken Sie auf „Test-Webhook senden“, um sich den Webhook an den ausgewählten Endpunkt senden zu lassen. Dies dauert in der Regel nur wenige Sekunden.
Aktualisieren Sie die Seite, dann erscheint der gerade gesendete Webhook in der Liste Ihrer Webhooks.
Wenn Sie auf einen Webhook klicken, werden die vollständige Anforderung und Ihre Antwort angezeigt. Dies ist vor allem für das Debugging ausgesprochen hilfreich.
Sie können einen bereits gesendeten Webhook erneut senden, indem Sie in der rechten oberen Ecke auf „Wiederholen“ klicken.
Verarbeiten von Events mithilfe des Endpunkts „Events“
Als Alternative zur Verwendung von Webhooks können Sie die Informationen auch direkt vom Endpunkt „Events“ abrufen.
Diese Methode ist beliebt, denn sie gibt Ihnen bessere Kontrolle über den Zeitpunkt der Verarbeitung von Events und Sie brauchen sich zudem nicht mit den komplizierteren Verfahren für fehlgeschlagene bzw. erneut gesendete Webhooks zu befassen.
Bei dieser Methode werden zu bestimmten Zeiten während des ganzen Tages mithilfe des Parameters created_at[gt] Aufrufe zur Auflistung von Events durchgeführt, um die seit dem letzten Aufruf erstellten Events aufzulisten.
Sie können auch bestimmte Events mithilfe der hier aufgeführten Parameter abrufen oder behandeln. Wenn Sie also beispielsweise nur Events für stornierte Lastschriftmandate (mandate cancelled) erhalten möchten, müssen Sie eine Anforderung senden, die etwa wie folgt aussieht:
GET https://api-sandbox.gocardless.com/events?action=cancelled&resource_type=mandate HTTP/1.1
Beachten Sie bitte, dass die meisten Events erstellt werden, wenn wir Berichte von der Bank erhalten (8:00–11:00 MEZ) und an die Bank senden (15:00–18:00 MEZ). Wir empfehlen Ihnen daher, die Endpunkte zur Mittagszeit und dann am Abend sowie zu allen weiteren gewünschten Zeiten abzurufen.