Webhooks absichern

Übersicht

Um die Authentizität und Integrität von Webhooks sicherzustellen, stellen wir einen X-Signature-Header bereit, der validiert werden kann. Dieser Header enthält eine mit Ihrem personal_secret erzeugte Signatur, die Sie prüfen können, um zu bestätigen, dass die Webhook-Anfrage legitim ist und nicht manipuliert wurde.

Wichtige Hinweise

Persönliches Secret festlegen: Falls Sie noch kein persönliches Secret festgelegt haben, beachten Sie, dass das Hinzufügen eines solchen den X-Signature-Header für alle ausgehenden Webhooks aktiviert. Stellen Sie sicher, dass Ihr Server diesen Header akzeptieren und prüfen kann.
Persönliches Secret erneuern: Falls Sie bereits ein persönliches Secret haben und dieses ändern, wird das neue Secret sofort für Webhook-Benachrichtigungen wirksam. Stellen Sie sicher, dass Ihr Server aktualisiert wird, um das neue Secret zu verwenden, um Unterbrechungen zu vermeiden.

Das persönliche Secret festlegen

Sie können Ihr persönliches Secret in Ihren Profileinstellungen auf unserer Plattform festlegen oder neu generieren. Gehen Sie dazu wie folgt vor:

Zu den Profileinstellungen gehen: Profileinstellungen
Den Bereich „Personal Secret” finden: Suchen Sie den mit „Personal Secret” beschrifteten Bereich.
Secret festlegen oder neu generieren:
- Ist noch kein Secret festgelegt, klicken Sie auf „Set Personal Secret”, um ein neues Secret zu generieren.
- Ist bereits ein Secret vorhanden, klicken Sie auf „Regenerate Secret”, um ein neues zu erstellen.

Wie der X-Signature-Header aufgebaut wird

Die txid aus dem Payload extrahieren:

Die txid (Transaktions-ID) ist eine eindeutige Kennung, die im Webhook-Payload enthalten ist. Diese ID wird als Teil des Signaturerzeugungsprozesses verwendet. Die txid mit einem persönlichen Secret kombinieren:

Das persönliche Secret ist ein gemeinsamer geheimer Schlüssel, der nur dem Sender (z. B. dem Webhook-Anbieter) und dem Empfänger (Ihrer Anwendung) bekannt ist. Dieser geheime Schlüssel stellt sicher, dass die Signatur nur von Parteien erzeugt und geprüft werden kann, die das Secret kennen. HMAC (Hash-based Message Authentication Code) generieren:

HMAC ist eine spezielle Art von Nachrichtenauthentifizierungscode (MAC), der eine kryptografische Hashfunktion und einen geheimen Schlüssel verwendet. In diesem Fall werden die txid und das persönliche Secret zur Erzeugung des HMAC verwendet. Der HMAC wird üblicherweise mit einem Hashing-Algorithmus wie SHA-256 erzeugt.

Den X-Signature-Header verifizieren

Wenn Sie einen Webhook empfangen, ist es wichtig, den X-Signature-Header zu prüfen, um sicherzustellen, dass die Anfrage von einer vertrauenswürdigen Quelle stammt. Im Folgenden finden Sie Beispiele, wie Sie diese Prüfung in Python, Java, PHP und JavaScript durchführen.

import hmac
import hashlib
import base64

def verify_signature(txid, received_signature, personal_secret):
    # Generate the expected signature
    expected_signature = base64.b64encode(hmac.new(
        personal_secret.encode(),
        txid.encode(),
        hashlib.sha256
    ).digest()).decode()

    # Compare the expected signature with the received signature
    return hmac.compare_digest(expected_signature, received_signature)

# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'

if verify_signature(txid, received_signature, personal_secret):
    print("Signature is valid.")
else:
    print("Invalid signature.")

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SignatureVerifier {
    public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(), "HmacSHA256");
        mac.init(secretKeySpec);

        byte[] signatureBytes = mac.doFinal(txid.getBytes());
        String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);

        return expectedSignature.equals(receivedSignature);
    }

    public static void main(String[] args) {
        try {
            String txid = "your_txid_here";
            String receivedSignature = "received_signature_here";
            String personalSecret = "your_personal_secret_here";

            if (verifySignature(txid, receivedSignature, personalSecret)) {
                System.out.println("Signature is valid.");
            } else {
                System.out.println("Invalid signature.");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

function verifySignature($txid, $receivedSignature, $personalSecret) {
    // Generate the expected signature
    $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));

    // Compare the expected signature with the received signature
    return hash_equals($expectedSignature, $receivedSignature);
}

// Example usage
$txid = 'your_txid_here';
$receivedSignature = 'received_signature_here';
$personalSecret = 'your_personal_secret_here';

if (verifySignature($txid, $receivedSignature, $personalSecret)) {
    echo "Signature is valid.";
} else {
    echo "Invalid signature.";
}

const crypto = require('crypto');

function verifySignature(txid, receivedSignature, personalSecret) {
    // Generate the expected signature
    const expectedSignature = crypto
        .createHmac('sha256', personalSecret)
        .update(txid)
        .digest('base64');

    // Compare the expected signature with the received signature
    return crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(receivedSignature));
}

// Example usage
const txid = 'your_txid_here';
const receivedSignature = 'received_signature_here';
const personalSecret = 'your_personal_secret_here';

if (verifySignature(txid, receivedSignature, personalSecret)) {
    console.log("Signature is valid.");
} else {
    console.log("Invalid signature.");
}

Fazit

Mit der Möglichkeit, Ihr personal_secret zu verwalten, haben Sie mehr Kontrolle über Ihre Webhook-Sicherheit. Stellen Sie stets sicher, dass der Webhook-Handler Ihres Servers aktualisiert wird, wann immer Sie das personal_secret ändern, um Unterbrechungen des Dienstes zu vermeiden. Bei Fragen oder Problemen wenden Sie sich bitte an den Support.