Technische Hinweise zur Einrichtung und Nutzung von Callbacks

    Inhalt dieses Artikels

    1. Vorbemerkungen
    2. Verifizierung der Signatur 

    1. Vorbemerkungen

    Callbacks ermöglichen es, Informationen zu definierten Ereignissen im plenigo-System auf andere Systeme zu übertragen. 
    Bei der Integration von plenigo ist es möglicherweise gewünscht, dass Drittsysteme Informationen zu Ereignisse empfangen, welche im plenigo System auftreten, damit diese Systeme entsprechend Aktionen ausführen können. 
    Zu diesem Zweck können sogenannte Callbacks im Merchant Backend definiert werden. 

    Hinweis: 
    Die meisten der Callback-Typen übermitteln Daten unmittelbar mit dem Auftreten eines Ereignisses. Eine Ausnahmen stellt der Callback-Typ "Kunde DSGVO-Daten" dar. Dieser Callback-Typ arbeitet asynchron und mit einer PromiseId. Die PromiseId dient der verzögerten Zuordnung der Daten. 
    Beispiele für Ereignisse: 
    • Die Anlage eines Kunden in plenigo soll automatisch auch an einen Kundendaten-Hub übermittelt werden. 
    • Die Änderung von Opt-In-Einstellungen über plenigo soll automatisch an ein Marketing-Tool übermittelt werden. 
    • Die Information über die Kündigung eines Abonnements soll automatisch an ein Newsletter-Versandtool übermittelt werden.

    2. Verifizierung der Signatur

    Signatur-Header für Callbacks 

    Jeder Callback wird über einen Signatur-Header signiert. 
    Der Header heißt plenigo-signature. 
    plenigo-signature: t=1492774577,s=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd 

    Der Header enthält zwei Elemente. Einen Zeitstempel, der den Zeitpunkt angibt, zu dem der Rückruf erzeugt wurde (t), und einen hashbasierten Nachrichtenauthentifizierungscode (HMAC) mit SHA-256 (s). 

    Um den Header zu verifizieren, gehen Sie wie folgt vor: 

    Schritt 1: Extrahieren des Zeitstempels und der Signaturen aus dem Header 
    Der Inhalt des Headers kann mit dem Zeichen "," (Komma) getrennt werden, um eine Liste von Elementen zu erhalten. Durch das Zeichen "=" (Gleichheitszeichen) als Trennzeichen kann jedes Element in ein Datenpaar aus einem Präfix und einem Wert unterteilt werden. 

    Werte der Präfixe:
    • "t" = Zeitstempel
    • "u" = unique Id 
    • "s" = eine Signatur oder mehrere Signaturen
    Eventuelle weitere Elemente können ignoriert werden.

    Schritt 2: Vorbereiten der Zeichenkette "signed_payload" 
    Die Zeichenfolge "signed_payload" wird durch eine Verkettung erstellt: 
    • Der Zeitstempel als String
    • Das Zeichen "." (Punkt) 
    • Der eigentliche JSON-Payload (d. h. der Anfrageinhalt) als String 

    Schritt 3: Bestimmung der erwarteten Signatur 
    Es wird ein HMAC Authentifizierungscode mit einer SHA256-Hash-Funktion benötigt. Das Signiergeheimnis des Endpunkts wird als Schlüssel und die Zeichenkette "signed_payload" als Nachricht verwendet.

    Schritt 4: Vergleichen Sie die Signaturen 
    Die Signatur (oder Signaturen) in der Kopfzeile sollten mit der erwarteten Signatur verglichen werden. 
    Für den Vergleich sollte die Differenz zwischen dem aktuellen Zeitstempel und dem empfangenen Zeitstempel erechnet werden um dann zu entscheiden ob die Differenz innerhalb einer akzeptablen Toleranz liegt. 

    Zum Schutz vor timing attacks (einr Variante eines Seitenkanalangriffs) empfiehlt es sich einen zeitlich konstanten String-Vergleich durchzuführen, um die erwartete Signatur mit jeder der empfangenen Signaturen zu vergleichen.
    Veröffentlicht