Webhook-Signaturen prüfen

Ein Webhook-Endpoint ist eine Tür in Ihr Bestellsystem — jedes eingehende Event muss beweisen, dass es wirklich von FlowAlp Pay stammt. Zwei Mechanismen greifen ineinander: der Signatur-Header auf dem Webhook selbst und die serverseitige Validierung gegen die Merchant API.

So funktioniert die Webhook-Signatur#

Jeder Webhook trägt den HTTP-Header X-Webhook-Signature. Sein Wert ist ein HMAC-SHA256 über den rohen Request-Body mit Ihrem Signing Key, kodiert als Hexadezimal in Kleinbuchstaben. Drei Details sind entscheidend:

• Signierte Daten: der rohe, unveränderte Request-Body — serialisieren Sie das geparste JSON vor dem Hashen niemals neu.
• Schlüssel-Kodierung: der Signing Key wird als einfacher UTF-8-String verwendet, nicht zuerst Base64-dekodiert.
• Signatur-Kodierung: das Ergebnis ist Hex in Kleinbuchstaben — nicht Base64.

<?php
// Reject any webhook whose signature does not match
$rawBody    = file_get_contents('php://input');
$received   = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$signingKey = getenv('FLOWALP_WEBHOOK_SIGNING_KEY');

// Lowercase hex HMAC-SHA256 of the raw body; the key is a plain UTF-8 string
$expected = hash_hmac('sha256', $rawBody, $signingKey);

if (!hash_equals($expected, $received)) {
    http_response_code(401); // non-2xx: the delivery counts as failed
    exit('invalid signature');
}

http_response_code(200);
// Queue the event for asynchronous, idempotent processing

Verwenden Sie hash_equals() (bzw. den Konstantzeit-Vergleich Ihrer Sprache) gegen Timing-Angriffe und beantworten Sie unsignierte oder ungültige Zustellungen mit einem Nicht-2xx-Status wie 401 — verarbeiten Sie sie niemals.

Nicht mit ApiSignature verwechseln#

Die Merchant API kennt einen zweiten, davon unabhängigen HMAC: den Authentifizierungsmodus ApiSignature für ausgehende API-Anfragen. Halten Sie beide auseinander:

<?php
function flowalpApiSignature(array $params, string $apiSecret): string
{
    ksort($params);
    $query = http_build_query($params, '', '&');
    return base64_encode(hash_hmac('sha256', $query, $apiSecret, true));
}

Die genauen Kodierungsregeln für ApiSignature finden Sie in der Merchant-API-Authentifizierung.

Credentials mit SignatureCheck validieren#

Die Ressource SignatureCheck prüft Instanzname, API Secret und — im Signaturmodus — Ihre HMAC-Implementierung, ohne etwas zu erzeugen. Rufen Sie sie beim Setup und aus Health-Checks auf:

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\SignatureCheck;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

try {
    $client->getOne(new SignatureCheck());
    // Credentials are valid
} catch (\FlowAlpPay\FlowAlpPayException $e) {
    // Wrong instance name or API secret
}

Details und Fehlermeldungen stehen auf der SignatureCheck-Referenzseite; das Client-Setup erklärt der PHP-SDK-Guide.

Verteidigung in der Tiefe#

• Lehnen Sie unsignierte oder ungültige Webhooks mit Nicht-2xx ab und alarmieren Sie bei wiederholten Fehlschlägen.
• Verarbeiten Sie verifizierte Events idempotent — Deduplizierung über Transaktions-ID plus Status.
• Rufen Sie bei geldrelevanten Statuswechseln die Transaktion zusätzlich über die API ab, bevor Sie erfüllen.
• Persistieren Sie das Prüfergebnis neben dem rohen Payload für Audits.