Sicurezza Webhook

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

Intestazioni della richiesta

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

Algoritmo di verifica

1. Leggete X-ConsentForge-Timestamp dall'intestazione della richiesta
2. Leggete X-ConsentForge-Signature dall'intestazione della richiesta
3. Costruite la stringa di firma: {timestamp}.{raw_request_body}
4. Calcolate HMAC-SHA256 della stringa di firma usando il vostro segreto webhook
5. Confrontate (in modo sicuro contro gli attacchi temporali) con la firma ricevuta
6. Rifiutate se il timestamp ha più di 5 minuti (protezione replay)

Esempi di codice

PHP

function verifyConsentForgeWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    // Rifiuta se troppo vecchio (5 minuti)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }

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

    return hash_equals($expected, $signature);
}

// Utilizzo in un controller 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) {
  // Rifiuta se troppo vecchio (5 minuti)
  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')
  );
}

// Utilizzo 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);
  // gestire il payload...
  res.json({ received: true });
});

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Rifiuta se troppo vecchio (5 minuti)
    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)

# Utilizzo 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()
    # gestire il payload...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Rifiuta se troppo vecchio (5 minuti)
  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

# Utilizzo 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)
    # gestire il payload...
    head :ok
  end
end

Idempotenza

Usate X-ConsentForge-Delivery-ID per deduplicare le consegne ripetute. Memorizzate gli ID di consegna elaborati e saltate i duplicati.

Rotazione del segreto

Per ruotare il vostro segreto webhook:

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