Proteggere i webhook

Proteggere i webhook

Panoramica

Per garantire l’autenticità e l’integrità dei webhook, forniamo un header X-Signature che può essere convalidato. Questo header contiene una firma generata usando il tuo personal_secret, che puoi verificare per confermare che la richiesta webhook sia legittima e non sia stata manomessa.

Note importanti

• Impostazione di un Personal Secret: Se non hai ancora impostato un personal secret, tieni presente che aggiungerne uno abiliterà l’header X-Signature su tutti i webhook in uscita. Assicurati che il tuo server possa accettare e verificare questo header.
• Rinnovo del Personal Secret: Se hai già un personal secret e scegli di modificarlo, il nuovo secret avrà effetto immediato sulle notifiche webhook. Assicurati che il tuo server venga aggiornato per usare il nuovo secret, per evitare interruzioni.

Impostare il Personal Secret

Puoi impostare o rigenerare il tuo personal secret accedendo alle impostazioni del profilo sulla nostra piattaforma. Segui questi passaggi:

1. Vai alle impostazioni del profilo: Impostazioni del profilo
2. Individua la sezione Personal Secret: Trova la sezione denominata “Personal Secret”.
3. Imposta o rigenera il secret:
   • Se non è impostato alcun secret, clicca su “Set Personal Secret” per generarne uno nuovo.
   • Se è già presente un secret, clicca su “Regenerate Secret” per crearne uno nuovo.

Come viene costruito l’header X-Signature

Estrazione del txid dal payload:

Il txid (identificativo di transazione) è un identificativo univoco incluso nel payload del webhook. Questo ID viene usato come parte del processo di generazione della firma. Combinazione del txid con un Personal Secret:

Il personal secret è una chiave segreta condivisa, conosciuta solo dal mittente (ad esempio il provider del webhook) e dal ricevente (la tua applicazione). Questa chiave segreta garantisce che la firma possa essere generata e verificata solo dalle parti che conoscono il secret. Generazione dell’HMAC (Hash-based Message Authentication Code):

HMAC è un tipo specifico di codice di autenticazione del messaggio (MAC) che utilizza una funzione di hash crittografica e una chiave segreta. In questo caso, il txid e il personal secret vengono usati per generare l’HMAC. L’HMAC viene tipicamente generato usando un algoritmo di hashing come SHA-256.

Verificare l’header X-Signature

Quando ricevi un webhook, è essenziale verificare l’header X-Signature per assicurarti che la richiesta provenga da una fonte affidabile. Di seguito trovi esempi su come eseguire questa verifica in Python, Java, PHP e JavaScript.

Python

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.")

Java

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();
        }
    }
}

PHP

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.";
}

JavaScript

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.");
}

Conclusione

Con la possibilità di gestire il tuo personal_secret, hai un maggiore controllo sulla sicurezza dei tuoi webhook. Assicurati sempre che il gestore webhook del tuo server venga aggiornato ogni volta che modifichi il personal_secret, per evitare interruzioni del servizio. Per qualsiasi domanda o problema, contatta il supporto.