Sicurezza webhook

Ogni richiesta webhook da ConsentForge include una firma HMAC-SHA256. Verifica questa firma prima di elaborare il payload per assicurarti che la richiesta sia autentica e non sia stata manomessa.

Header della richiesta

Header	Descrizione
X-ConsentForge-Signature	Digest hex HMAC-SHA256 di {timestamp}.{body}
X-ConsentForge-Timestamp	Timestamp Unix (secondi) quando l'evento è stato inviato
X-ConsentForge-Delivery-ID	ID univoco per questa consegna (usa per l'idempotenza)

Algoritmo di verifica

1. Leggi X-ConsentForge-Timestamp dall'header della richiesta
2. Leggi X-ConsentForge-Signature dall'header della richiesta
3. Costruisci la stringa di firma: {timestamp}.{raw_request_body}
4. Calcola HMAC-SHA256 della stringa di firma usando il tuo segreto webhook
5. Confronta (timing-safe) con la firma ricevuta
6. Rifiuta se il timestamp ha più di 5 minuti (protezione da replay)

Esempi di codice

PHP

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

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

    return hash_equals($expected, $signature);
}

// Usage in a Laravel controller:
$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) {
  // Reject if too old (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')
  );
}

// Usage in 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);
  // handle payload...
  res.json({ received: true });
});

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Reject if too old (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)

# Usage in 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()
    # handle payload...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Reject if too old (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

# Usage in 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)
    # handle payload...
    head :ok
  end
end

Idempotenza

Usa X-ConsentForge-Delivery-ID per deduplicare le consegne ritentate. Memorizza gli ID di consegna elaborati e salta i duplicati.

Rotazione del segreto

Per ruotare il tuo segreto webhook:

1. Genera un nuovo segreto nel Dashboard (il vecchio segreto rimane attivo per 24h)
2. Aggiorna il tuo server per usare il nuovo segreto
3. Dopo 24h, il vecchio segreto viene invalidato