"x-signature": "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="Ein Webhook kann verwendet werden, um eine andere Anwendung über Ereignisse zu informieren. Webhooks werden im Allgemeinen durch ein Ereignis ausgelöst, um beispielsweise Ihre Anwendung über eine Statusänderung einer Entität zu benachrichtigen.
Es gibt zwei Konzepte, um eine Anwendung über Änderungen zu informieren. Das eine ist Polling und das andere ist Pushing. Polling ist nicht optimal, da es normalerweise keine Aktualisierung gibt und der Poll verschwendet wird. Aus diesem Grund verwenden wir Pushing-Updates. Webhooks sind ein Konzept, bei dem die Anwendung, die an Aktualisierungen interessiert ist, durch eine HTTP-Anfrage benachrichtigt wird. Das heißt, die Anwendung kann sich für bestimmte Ereignisse registrieren und wir senden eine HTTP-Anfrage, wenn ein solches Ereignis eintritt.
Alle Konfigurationsdetails können innerhalb des Space-Links eingestellt Space > Settings > General > Webhook Listeners. Hier können Sie die URL festlegen und aus den verschiedenen Ereignissen wählen, für die Sie einen HTTP-Aufruf erhalten möchten.
Alle URLs, an die ein Webhook geliefert werden soll, werden zentral in Space > Settings > General > Webhooks URLs.
Klicken Sie, um eine Webhook-URL hinzuzufügen. Die zentrale Verwaltung der URLs erleichtert Ihnen die Verwaltung von Änderungen an den URLs zu verwalten, damit Sie nicht jede Webhook-Listener-Konfiguration anfassen müssen.
Sie können eine Webhook-URL auch programmatisch über unsere API oder unser SDK erstellen: example here.
|
Warning
|
Wichtiges Update zum Webhook-Signierung Mechanismus: Wir empfehlen Ihnen dringend, so bald wie möglich mit der Integration des neuen Signatur-Mechanismus in Ihre Webhooks zu beginnen. Dies wird einen reibungslosen Übergang gewährleisten, wenn die Funktion obligatorisch wird. Nach der Übergangszeit wird die bisherige Webhook-Verarbeitung schrittweise eingestellt. |
Warum wir Webhook Payload Signing implementiert haben
In unserem ständigen Bestreben, die höchsten Standards der Datensicherheit und -integrität aufrechtzuerhalten, haben wir einen robusten Payload-Signierungsmechanismus für unsere Webhooks implementiert. Dieser Ansatz basiert auf der Verwendung von Kryptographie mit öffentlichen und privaten Schlüssel, kombiniert mit sicheren Hash-Algorithmen, um die gesendeten Daten zu authentifizieren und zu verifizieren.
Auf diese Weise werden die Sicherheit und Zuverlässigkeit unserer Webhooks verbessert:
Erzeugung und Verwaltung des Webhook-Schlüsselpaars:
Wir generieren ein kryptografisches Schlüsselpaar, das aus einem privaten und einem öffentlichen Schlüssel besteht. Der private Schlüssel, der sicher in unserer Datenbank gespeichert ist, wird zum Signieren der Webhook-Payloads verwendet.
Der öffentliche Schlüssel wird mit Ihnen geteilt, um die Überprüfung dieser Signaturen zu ermöglichen und kann über die eindeutig generierte keyId mittels read Endpunkt im
Webhook Encryption Service.
Signatur Vorgang:
Jedes Mal, wenn eine Webhook-Nutzlast versendet wird, wird die Nutzlast zunächst mit dem SHA-256-Hashing-Algorithmus, ergänzt durch den Elliptic Curve Digital Signature Algorithm (ECDSA), gehasht, um eine eindeutige und sichere Darstellung des Inhalts der Nutzlast zu erstellen.
Dieser Hash wird dann mit unserem privaten Schlüssel verschlüsselt und bildet eine digitale Signatur. Diese digitale Signatur ist entscheidend, um die Integrität und Authentizität der Nutzdaten zu gewährleisten. Anschließend fügen wir diese Signatur der ausgehenden HTTP-Anfrage des Webhooks in Form einer benutzerdefinierten Kopfzeile namens x-signature hinzu.
Der Wert dieses Headers enthält wichtige Details wie den verwendeten Algorithmus (SHA256withECDSA`), einen eindeutigen Schlüsselbezeichner (keyId) und die eigentliche signature.
Dieser Header spielt eine wichtige Rolle, da er den Empfänger des Webhooks in die Lage versetzt, die Authentizität der empfangenen Daten anhand der bereitgestellten Informationen zu überprüfen und sicherzustellen, dass die Nutzdaten tatsächlich aus einer vertrauenswürdigen Quelle stammen und während der Übertragung nicht verändert wurden.
Sichere Übertragung der Nutzdaten:
Die Nutzdaten werden zusammen mit Ihrer digitalen Signatur an Sie übermittelt. Dieses Verfahren stellt sicher, dass die Nutzdaten genau so bei Ihnen ankommen, wie wir sie gesendet haben, frei von Manipulationen oder unbefugten Änderungen.
Verifizierung durch Kunden:
Nach Erhalt einer Webhook-Nutzlast können Sie deren Authentizität und Integrität überprüfen. Indem Sie die Nutzdaten mit der gleichen Methode hashen und die Signatur mit dem abgerufenen öffentlichen Schlüssel entschlüsseln, können Sie bestätigen, dass die Nutzdaten legitim und unverändert sind. Eine Übereinstimmung zwischen dem von Ihnen berechneten Hash und der entschlüsselten Signatur zeigt an, dass die Nutzdaten authentisch sind und tatsächlich von unserem System gesendet wurden.
Der Prozess der Überprüfung der Authentizität und Integrität der empfangenen Webhook-Nutzdaten wird programmatisch über unser SDK durchgeführt. Nach dem Empfang eines Webhook-Payloads kann Ihre Anwendung die bereitgestellten SDK-Methoden zur Validierung des Payloads verwenden.
"x-signature": "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="Ein Listener kann auf Zustandsänderungen von bestimmten Entitäten hören. Das bedeutet, wenn eine Entität in den angegebenen Zustand wechselt wird die URL aufgerufen. Nur certain entities können von einem Webhook-Listener abonniert werden. Ein Webhook Listener kann unter Link erstellt Space > Settings > General > Webhook Listeners.
Sie können einen Listener auch programmatisch mit unserer API oder unserem SDK erstellen: example here.
Ein Protokoll aller ausgelösten Webhooks kann unter dem Link eingesehen Space > Connect > Webhooks > Invocations. Wenn Sie auf den Aufruf klicken, können Sie den Fehler sehen, falls der Webhook fehlgeschlagen ist, einschließlich der Antwort, die wir von Ihrem Server erhalten haben.
|
Note
|
Wir versuchen, das Ereignis zuzustellen, bis wir eine bestimmte Anzahl von Versuchen erreicht haben. Die Zeit zwischen den Versuchen wird nach jedem Versuch erhöht. Wenn die Zustellung weiterhin fehlschlägt wird der Listener deaktiviert, um zu verhindern, dass ein potenziell toter Listener weiter aufgerufen wird. |
Die HTTP-Anfrage, die bei einer Zustandsänderung einer Entität gesendet wird, enthält die folgenden Daten:
eventId: Eine eindeutige ID, die die Zustandsänderung identifiziert. Diese ist bei jeder Benachrichtigung anders.
entityId: Die ID der Entität, die geändert wurde.
listenerEntityId: Die Listener-Entität gibt an, welcher Entitätstyp geändert wurde.
listenerEntityTechnicalName: Der technische Name der Listener-Entität liefert einen Namen für den Entitätstyp.
spaceId: Die Space ID, zu der die geänderte Entität gehört.
webhookListenerId: Die ID des Listeners.
timestamp: Der Zeitpunkt, an dem die Zustandsänderung stattgefunden hat.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000"
}Sobald Sie die Benachrichtigung über Ihre URL erhalten, sollten Sie unsere API aufrufen, um den Status der geänderten Entität zu lesen. Dies hat den großen Vorteil, dass wir Sie auch über ungesicherte URLs benachrichtigen können und keine sensiblen Daten direkt mit Ihrem System austauschen müssen.
|
Note
|
Wir empfehlen die Verwendung von HTTP(s), d.h. eine verschlüsselte Verbindung, wenn Sie die oben erläuterte digital signierte Nutzlast verwenden wollen. |
Um den Zustand der Entität und weitere Details zu lesen, sollten Sie den entsprechenden read Endpunkt im
Link verwenden API Documentation using the entityId.
Die HTTP-Anfrage, die bei einer Zustandsänderung einer Entität gesendet wird, enthält nun ein zusätzliches Feld state, das Informationen über die Aktualisierung des Zustands der überwachten Entität liefert. Diese Verbesserung ist ein Ergebnis der Implementierung unseres Webhook-Verschlüsselungsmechanismus.
Das Payload-Feld state liefert direkte Informationen über die Statusaktualisierung der Entität, so dass zusätzliche API-Aufrufe zur Abfrage des Status überflüssig sind.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000",
"state": "PROCESSING"
}Mit der Einführung des Feldes state wird die Notwendigkeit, zusätzliche API-Aufrufe an unser System zu tätigen, um den Status der geänderten Entität auszulesen, stark reduziert, sobald Sie die Benachrichtigung an Ihrem Endpunkt erhalten. Durch diese Verbesserung wird nicht nur der Prozess rationalisiert, sondern auch die Sicherheit aufrechterhalten, indem der Austausch sensibler Daten minimiert wird.
Damit die Webhooks ordnungsgemäß funktionieren, ist es wichtig, dass Ihre Firewall- und Serverkonfiguration die Kommunikation mit unseren Servern zulässt. Dieses Dokument enthält alle Informationen, die Sie benötigen, um Ihre Firewalls so zu konfigurieren, dass der Datenverkehr zwischen Ihrer Infrastruktur und unseren Diensten möglich ist, Dadurch wird das Risiko von Kommunikationsfehlern/Problemen minimiert.
In diesem Dokument wird davon ausgegangen, dass der Händler mit den Verfahren zur Konfiguration von Firewalls, Routern oder anderen Geräten, die zum Blockieren des Datenverkehrs im Händlernetz verwendet werden, vertraut ist.
Die folgenden Listen enthalten IP-Adressen, die in die Whitelist aufgenommen werden müssen, um die Kommunikation zwischen Ihrer Infrastruktur und unserer Plattform zu ermöglichen. Wir senden die HTTP-Anfrage von diesen IP-Adressen.