Zum Hauptinhalt springen

Webhooks

Mithilfe von Webhooks kann Ihre Anwendung Echtzeitbenachrichtigungen erhalten, wenn bestimmte Ereignisse in unserem System eintreten. Anstatt die API regelmäßig auf Änderungen abzufragen, senden wir Aktualisierungen direkt über HTTP-POST-Anfragen an Ihren Endpunkt, sobald sie eintreten. Dies ist die empfohlene Vorgehensweise, um auf Statusänderungen zu reagieren – beispielsweise um die Auftragsabwicklung auszulösen, wenn eine Transaktion den Status Fulfill erreicht (siehe Transaktionsstatus).

Typische Anwendungsfälle​

  • Sofortige Auftragsabwicklung – Lösen Sie die Kommissionierung im Lager oder die digitale Produktlieferung aus, sobald eine Transaktion autorisiert oder abgewickelt wurde.
  • Automatisierte Buchhaltung – Leiten Sie Zahlungsdaten direkt in Ihr ERP- oder Buchhaltungssystem weiter, ohne dass eine manuelle Dateneingabe erforderlich ist.
  • Bestandssynchronisierung — Aktualisieren Sie die Lagerbestände über alle Vertriebskanäle hinweg, sobald ein Verkauf abgeschlossen ist.
  • Proaktive Abonnement-Wiederherstellung — Reagieren Sie sofort, wenn eine Abonnementzahlung fehlschlägt, beispielsweise durch den Versand einer Mahn-E-Mail.

Einrichtung und Konfiguration​

Die Konfiguration von Webhooks erfolgt in zwei Schritten: Registrieren Sie eine Webhook-URL (den Endpunkt auf Ihrem Server, der die Payloads empfängt) und erstellen Sie anschließend einen Webhook-Listener (der festlegt, welche Entitätstypen und Zustände eine Benachrichtigung an diese URL auslösen).

Webhook-URLs​

Webhooks werden zentral unter Space > Einstellungen > Allgemein > Webhook-URLs verwaltet. Da die URL an einer Stelle gespeichert ist, können Sie Ihren Endpunkt ändern, ohne die einzelnen Listener-Konfigurationen anzupassen. Sie können Webhook-URLs auch programmgesteuert mithilfe unserer API oder unserer SDKs erstellen.

Webhook-Listener​

Webhook-Listener werden unter Space > Einstellungen > Allgemein > Webhook-Listener konfiguriert. Für jeden Listener legen Sie Folgendes fest:

  • welcher Entitätstyp überwacht werden soll (z. B. „Transaction“, „Subscription“ – nur bestimmte Entitäten können abonniert werden; die Liste der verfügbaren Entitäten wird beim Anlegen eines Listeners angezeigt),
  • welche Zustände eine Benachrichtigung auslösen sollen oder ob alle Zustandsänderungen berücksichtigt werden sollen,
  • ob die Signierung der Nutzdaten (und damit das Feld state) aktiviert ist,
  • weitere Metadaten wie Name, Identität, Löschzeitplan und Versionierung.

Webhooks empfangen​

Wenn ein Ereignis ausgelöst wird, senden wir eine HTTP-POST-Anfrage an die von Ihnen registrierte URL. Ihr Endpunkt muss eine HTTP-200-Antwort zurückgeben, um den Empfang zu bestätigen.

Wenn Ihr Endpunkt die Zustellung nicht bestätigt, führt PostFinance Checkout über einen Zeitraum von bis zu 80 Stunden Wiederholungsversuche mit zunehmend längeren Intervallen durch. Nach 14 fehlgeschlagenen Versuchen wird der Listener automatisch deaktiviert, um endlose Versuche bei einem nicht reagierenden Endpunkt zu vermeiden.

Alle Webhook-Aufrufe – ob erfolgreich oder fehlgeschlagen – werden unter Space > Einstellungen > Allgemein > Webhook-Aufrufe protokolliert, einschließlich der Fehlerdetails und der von Ihrem Server zurückgegebenen Antwort. Hier sollten Sie als Erstes nachsehen, wenn Benachrichtigungen nicht wie erwartet eintreffen.

Struktur der Webhook-Nutzdaten​

Die Basis-Nutzlast enthält Metadaten zum Ereignis – keine Geschäftsdaten. Ihre Anwendung muss bei Bedarf einen weiteren API-Aufruf ausführen, um die Details der Entität abzurufen.

FeldBeschreibung
eventIdEindeutige ID des Ereignisses
entityIdID der Entität, die sich geändert hat
listenerEntityIdID des Entitätstyps
listenerEntityTechnicalNameTechnischer Name des Entitätstyps
spaceIdIhre Space-ID
webhookListenerIdID des Listeners
timestampZeitpunkt des Ereignisses
state (optional)Status der Entität, enthalten, wenn die Signierung der Nutzdaten aktiviert ist

Beispiel für eine einfache Nutzlast​

{
  "eventId": 138833842,
  "entityId": 63762876,
  "listenerEntityId": 1472041829003,
  "listenerEntityTechnicalName": "Transaction",
  "spaceId": 30140,
  "webhookListenerId": 285874,
  "timestamp": "2022-08-23T14:20:53+0000"
}

Nutzlast mit Status (vorzeichenbehaftet)​

{
  "eventId": 138833842,
  "entityId": 63762876,
  "listenerEntityId": 1472041829003,
  "listenerEntityTechnicalName": "Transaction",
  "spaceId": 30140,
  "webhookListenerId": 285874,
  "timestamp": "2022-08-23T14:20:53+0000",
  "state": "PROCESSING"
}

Wenn das Feld state vorhanden ist, kann Ihre Anwendung direkt auf die Statusänderung reagieren – wodurch der zusätzliche API-Aufruf zur Überprüfung des Entitätsstatus entfällt.

Sicherheit: Signierung der Nutzdaten​

Ein robuster Signaturmechanismus auf Basis von ECDSA mit SHA-256 gewährleistet die Authentizität und Integrität jeder Nutzlast: Er belegt, dass die Benachrichtigung tatsächlich von uns stammt und nicht manipuliert wurde. Nutzdaten werden gehasht und mit einem privaten Schlüssel signiert; der dazugehörige öffentliche Schlüssel wird über den Webhook-Verschlüsselungsdienst mithilfe eines keyId bereitgestellt. Die Signierung von Nutzdaten wird pro Listener aktiviert.

Signierte Anfragen enthalten einen x-signature-Header:

x-signature: algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+...
FeldBeschreibung
algorithmImmer SHA256withECDSA
keyIdKennung des öffentlichen Schlüssels, der zur Überprüfung der Signatur verwendet wird
signatureDie codierte Signatur selbst

Um eine Nutzlast zu überprüfen, rufen Sie den öffentlichen Schlüssel für keyId von PostFinance Checkout ab und überprüfen Sie die Signatur anhand der empfangenen Nutzlast. Wir empfehlen die Verwendung eines unserer offiziellen SDKs – diese bieten integrierte Methoden, die das Abrufen des Schlüssels und die Überprüfung der Signatur für Sie übernehmen.

warnung

Die Signierung der Nutzdaten ist obligatorisch. Integrieren Sie die Signaturprüfung bereits zu Beginn Ihrer Entwicklung.

warnung

Stellen Sie Ihren Webhook-Endpunkt stets über HTTPS bereit, um die Nutzdaten und Header während der Übertragung zu schützen.

Anforderungen an die Firewall​

Um die Zustellung von Webhooks zu gewährleisten, lassen Sie eingehende HTTPS-Anfragen von den folgenden IP-Adressen in Ihrer Firewall und bei Ihrem Hosting-Anbieter zu:

52.211.247.160
52.211.171.77
52.211.239.229
52.211.209.173
52.208.210.84
52.212.109.85
52.210.89.1
52.212.185.152
52.212.192.130

Kurze Checkliste​

  • Konfigurieren Sie die Ziel-URL und aktivieren Sie die Payload-Signatur (obligatorisch – dadurch wird auch das Feld state bereitgestellt).
  • Definieren Sie einen Webhook-Listener (über das Portal oder die API) für die Entitäten und Zustände, die Sie interessieren.
  • Geben Sie von Ihrem Endpunkt aus HTTP 200 zurück, um jede Zustellung zu bestätigen.
  • Implementieren Sie serverseitige Logik, um das x-signature zu überprüfen, das state direkt zu analysieren oder die Entität über die API abzurufen.
  • Überwachen Sie die Aufrufe des Webhooks in Ihrem Space und nehmen Sie bei Bedarf Anpassungen vor.

Fehlerbehebung​