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 la solicitud

Encabezado	Descripción
X-ConsentForge-Signature	Digesto 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 (seguro contra temporización) 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 {
    // Rechazar si es demasiado antigua (5 minutos)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }

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

    return hash_equals($expected, $signature);
}

// Uso en un controlador 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) {
  // Rechazar si es demasiado antigua (5 minutos)
  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')
  );
}

// Uso en 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);
  // manejar el payload...
  res.json({ received: true });
});

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Rechazar si es demasiado antigua (5 minutos)
    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)

# Uso en 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()
    # manejar el payload...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Rechazar si es demasiado antigua (5 minutos)
  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

# Uso en 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)
    # manejar el 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 anterior sigue activo durante 24 horas)
2. Actualice su servidor para usar el nuevo secreto
3. Después de 24 horas, el secreto anterior queda invalidado