Seguridad de webhooks

Cada solicitud de webhook de ConsentForge incluye una firma HMAC-SHA256. Verifique esta firma antes de procesar el payload para asegurarse de que la solicitud es genuina y no ha sido manipulada.

Encabezados de solicitud

Encabezado	Descripción
X-ConsentForge-Signature	Resumen hexadecimal HMAC-SHA256 de {timestamp}.{body}
X-ConsentForge-Timestamp	Marca de tiempo Unix (segundos) cuando se envió el evento
X-ConsentForge-Delivery-ID	ID único para esta entrega (use para idempotencia)

Algoritmo de verificación

1. Lea X-ConsentForge-Timestamp del encabezado de la solicitud
2. Lea X-ConsentForge-Signature del encabezado de la solicitud
3. Construya la cadena de firma: {timestamp}.{raw_request_body}
4. Calcule HMAC-SHA256 de la cadena de firma usando su secreto de webhook
5. Compare (con seguridad de tiempo) con la firma recibida
6. Rechace si la marca de tiempo tiene más de 5 minutos de antigüedad (protección contra repetición)

Ejemplos de código

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

Idempotencia

Use X-ConsentForge-Delivery-ID para deduplicar entregas reintentadas. Almacene los IDs de entregas procesadas y omita los duplicados.

Rotación de secretos

Para rotar su secreto de webhook:

1. Genere un nuevo secreto en el Panel (el secreto antiguo sigue activo durante 24h)
2. Actualice su servidor para usar el nuevo secreto
3. Después de 24h, el secreto antiguo se invalida