Sécurité des webhooks

Principe

MercyPay-Signature: t=1791022800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

• t est l’heure d’envoi, en secondes depuis 1970 ;
• v1 est le HMAC-SHA256 en hexadécimal de la chaîne {t}.{corps brut}, calculé avec le secret de l’endpoint.

1. Lisez le corps tel qu’il est reçu, en octets, sans le parser.
2. Refusez la requête si t a plus de 5 minutes d’écart avec votre horloge : une requête ancienne rejouée est ainsi rejetée.
3. Calculez le HMAC-SHA256 de {t}.{corps brut} avec votre secret.
4. Comparez-le à temps constant avec chaque valeur v1 de l’en-tête. Une seule doit correspondre.

Exemple en PHP

<?php

$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_MERCYPAY_SIGNATURE'] ?? '';
$secret = getenv('MERCYPAY_WEBHOOK_SECRET');

$timestamp = null;
$signatures = [];

foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');

    if ($key === 't') {
        $timestamp = (int) $value;
    } elseif ($key === 'v1') {
        $signatures[] = $value;
    }
}

$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
$valid = $timestamp && abs(time() - $timestamp) <= 300
    && array_filter($signatures, fn ($signature) => hash_equals($expected, $signature)) !== [];

if (! $valid) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);

Autres en-têtes

Changer de secret

Bonnes pratiques

• Gardez le secret dans votre gestionnaire de secrets, jamais dans le code.
• Refusez tout événement dont la signature ne correspond pas.
• Gardez votre horloge à l’heure (NTP) : la tolérance est de 5 minutes.
• Ne vous fiez pas à l’ordre d’arrivée : utilisez le status de la ressource.
• Si un secret fuite, régénérez-le sans attendre.