Sécuriser les webhooks

Sécuriser les webhooks

Vue d’ensemble

Pour garantir l’authenticité et l’intégrité des webhooks, nous fournissons un en-tête X-Signature qui peut être validé. Cet en-tête contient une signature générée à l’aide de votre personal_secret, que vous pouvez vérifier pour confirmer que la requête webhook est légitime et n’a pas été altérée.

Remarques importantes

• Définir un secret personnel : Si vous n’avez pas encore défini de secret personnel, sachez que l’ajout d’un secret activera l’en-tête X-Signature sur tous les webhooks sortants. Assurez-vous que votre serveur peut accepter et vérifier cet en-tête.
• Renouveler votre secret personnel : Si vous avez déjà un secret personnel et choisissez de le modifier, le nouveau secret prendra effet immédiatement sur les notifications webhook. Assurez-vous que votre serveur est mis à jour pour utiliser le nouveau secret afin d’éviter toute interruption.

Définir le secret personnel

Vous pouvez définir ou régénérer votre secret personnel en accédant aux paramètres de votre profil sur notre plateforme. Suivez ces étapes :

1. Accédez aux paramètres du profil : Paramètres du profil
2. Repérez la section du secret personnel : Trouvez la section intitulée « Personal Secret ».
3. Définissez ou régénérez le secret :
   • Si aucun secret n’est défini, cliquez sur « Set Personal Secret » pour générer un nouveau secret.
   • Si un secret est déjà présent, cliquez sur « Regenerate Secret » pour en créer un nouveau.

Comment l’en-tête X-Signature est construit

Extraction du txid depuis le payload :

Le txid (identifiant de transaction) est un identifiant unique inclus dans le payload du webhook. Cet identifiant est utilisé dans le processus de génération de la signature. Combinaison du txid avec un secret personnel :

Le secret personnel est une clé secrète partagée connue uniquement de l’émetteur (par exemple le fournisseur du webhook) et du récepteur (votre application). Cette clé secrète garantit que la signature ne peut être générée et vérifiée que par les parties qui connaissent le secret. Génération du HMAC (Hash-based Message Authentication Code) :

HMAC est un type spécifique de code d’authentification de message (MAC) qui utilise une fonction de hachage cryptographique et une clé secrète. Dans ce cas, le txid et le secret personnel sont utilisés pour générer le HMAC. Le HMAC est généralement généré à l’aide d’un algorithme de hachage comme SHA-256.

Vérifier l’en-tête X-Signature

Lorsque vous recevez un webhook, il est essentiel de vérifier l’en-tête X-Signature pour vous assurer que la requête provient d’une source fiable. Voici des exemples de vérification en Python, Java, PHP et 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.");
}

Conclusion

Grâce à la possibilité de gérer votre personal_secret, vous disposez d’un meilleur contrôle sur la sécurité de vos webhooks. Assurez-vous toujours que le gestionnaire de webhooks de votre serveur est mis à jour chaque fois que vous modifiez le personal_secret, afin d’éviter toute interruption de service. Pour toute question ou problème, veuillez contacter le support.