Verificare la firma dei webhook

Un endpoint webhook è una porta d'ingresso nel tuo sistema ordini: ogni evento in arrivo deve dimostrare di provenire davvero da FlowAlp Pay. Due meccanismi lavorano insieme: l'header di firma sul webhook stesso e la convalida lato server tramite la Merchant API.

Come funziona la firma dei webhook#

Ogni webhook porta l'header HTTP X-Webhook-Signature. Il valore è un HMAC-SHA256 calcolato sul body grezzo della richiesta con la tua signing key, codificato in esadecimale minuscolo. Tre dettagli contano:

• Dati firmati: il body grezzo e non modificato della richiesta — non riserializzare mai il JSON già parsato prima dell'hash.
• Codifica della chiave: la signing key si usa come stringa UTF-8 semplice; non va decodificata da Base64.
• Codifica della firma: il risultato è hex minuscolo — non 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

Usa hash_equals() (o il confronto a tempo costante del tuo linguaggio) per evitare attacchi di timing e rispondi alle consegne senza firma o con firma non valida con uno stato non-2xx come 401 — senza mai elaborarle.

Non confonderla con ApiSignature#

La Merchant API conosce un secondo HMAC, distinto: la modalità di autenticazione ApiSignature per le richieste API in uscita. Tienili separati:

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

Le regole esatte di codifica dei parametri per ApiSignature sono documentate in Autenticazione della Merchant API.

Convalida le credenziali con SignatureCheck#

La risorsa SignatureCheck verifica instance name, API Secret e — in modalità firma — la tua implementazione HMAC, senza creare nulla. Chiamala durante il setup e dagli health check:

<?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
}

Dettagli e risposte d'errore sono nella pagina di riferimento SignatureCheck; la configurazione del client è nella guida all'SDK PHP.

Difesa in profondità#

• Rifiuta i webhook senza firma o con firma non valida con una risposta non-2xx e crea un allarme sui fallimenti ripetuti.
• Elabora gli eventi verificati in modo idempotente — deduplica su ID transazione più stato.
• Per i cambi di stato rilevanti per il denaro, recupera in aggiunta la transazione via API prima di evadere.
• Salva l'esito della verifica accanto al payload grezzo per gli audit.