Sécurité des webhooks

Chaque requête webhook de ConsentForge inclut une signature HMAC-SHA256. Vérifiez cette signature avant de traiter la charge utile pour vous assurer que la requête est authentique et n'a pas été falsifiée.

En-têtes de la requête

En-tête	Description
X-ConsentForge-Signature	Résumé hexadécimal HMAC-SHA256 de {timestamp}.{body}
X-ConsentForge-Timestamp	Horodatage Unix (secondes) lors de l'envoi de l'événement
X-ConsentForge-Delivery-ID	ID unique pour cette livraison (utilisez-le pour l'idempotence)

Algorithme de vérification

1. Lisez X-ConsentForge-Timestamp depuis l'en-tête de la requête
2. Lisez X-ConsentForge-Signature depuis l'en-tête de la requête
3. Construisez la chaîne de signature : {timestamp}.{raw_request_body}
4. Calculez le HMAC-SHA256 de la chaîne de signature en utilisant votre secret webhook
5. Comparez (de manière sécurisée au niveau du timing) avec la signature reçue
6. Rejetez si l'horodatage a plus de 5 minutes (protection contre les attaques par rejeu)

Exemples de code

PHP

function verifyConsentForgeWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    // Rejeter si trop ancien (5 minutes)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }

    $signingString = $timestamp . '.' . $rawBody;
    $expected = hash_hmac('sha256', $signingString, $secret);

    return hash_equals($expected, $signature);
}

// Utilisation dans un contrôleur Laravel :
$rawBody   = $request->getContent();
$signature = $request->header('X-ConsentForge-Signature');
$timestamp = $request->header('X-ConsentForge-Timestamp');
$secret    = config('services.consentforge.webhook_secret');

if (!verifyConsentForgeWebhook($rawBody, $signature, $timestamp, $secret)) {
    return response('Unauthorized', 401);
}

$payload = $request->json()->all();

Node.js

const crypto = require('crypto');

function verifyConsentForgeWebhook(rawBody, signature, timestamp, secret) {
  // Rejeter si trop ancien (5 minutes)
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
    return false;
  }

  const signingString = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// Utilisation avec Express :
app.post('/webhooks/consentforge', express.raw({ type: '*/*' }), (req, res) => {
  const valid = verifyConsentForgeWebhook(
    req.body.toString(),
    req.headers['x-consentforge-signature'],
    req.headers['x-consentforge-timestamp'],
    process.env.CONSENTFORGE_WEBHOOK_SECRET
  );

  if (!valid) return res.status(401).send('Unauthorized');

  const payload = JSON.parse(req.body);
  // traiter la charge utile...
  res.json({ received: true });
});

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Rejeter si trop ancien (5 minutes)
    if abs(time.time() - int(timestamp)) > 300:
        return False

    signing_string = f"{timestamp}.{raw_body}"
    expected = hmac.new(
        secret.encode('utf-8'),
        signing_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# Utilisation avec Flask :
from flask import request, abort
import os

@app.route('/webhooks/consentforge', methods=['POST'])
def handle_webhook():
    raw_body = request.get_data(as_text=True)
    valid = verify_consentforge_webhook(
        raw_body,
        request.headers.get('X-ConsentForge-Signature'),
        request.headers.get('X-ConsentForge-Timestamp'),
        os.environ['CONSENTFORGE_WEBHOOK_SECRET']
    )
    if not valid:
        abort(401)
    payload = request.get_json()
    # traiter la charge utile...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Rejeter si trop ancien (5 minutes)
  return false if (Time.now.to_i - timestamp.to_i).abs > 300

  signing_string = "#{timestamp}.#{raw_body}"
  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, signing_string)

  Rack::Utils.secure_compare(expected, signature)
end

# Utilisation avec Rails :
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def consentforge
    raw_body = request.body.read
    valid = verify_consentforge_webhook(
      raw_body,
      request.headers['X-ConsentForge-Signature'],
      request.headers['X-ConsentForge-Timestamp'],
      ENV['CONSENTFORGE_WEBHOOK_SECRET']
    )
    return head :unauthorized unless valid

    payload = JSON.parse(raw_body)
    # traiter la charge utile...
    head :ok
  end
end

Idempotence

Utilisez X-ConsentForge-Delivery-ID pour dédupliquer les livraisons retentées. Stockez les ID de livraison traités et ignorez les doublons.

Rotation du secret

Pour pivoter votre secret webhook :

1. Générez un nouveau secret dans le tableau de bord (l'ancien secret reste actif pendant 24h)
2. Mettez à jour votre serveur pour utiliser le nouveau secret
3. Après 24h, l'ancien secret est invalidé