Segurança de Webhooks

Cada pedido de webhook do ConsentForge inclui uma assinatura HMAC-SHA256. Verifique esta assinatura antes de processar o payload para garantir que o pedido é genuíno e não foi adulterado.

Cabeçalhos do pedido

Cabeçalho	Descrição
X-ConsentForge-Signature	Resumo hexadecimal HMAC-SHA256 de {timestamp}.{body}
X-ConsentForge-Timestamp	Timestamp Unix (segundos) de quando o evento foi enviado
X-ConsentForge-Delivery-ID	ID único para esta entrega (use para idempotência)

Algoritmo de verificação

1. Leia X-ConsentForge-Timestamp do cabeçalho do pedido
2. Leia X-ConsentForge-Signature do cabeçalho do pedido
3. Construa a cadeia de assinatura: {timestamp}.{raw_request_body}
4. Calcule o HMAC-SHA256 da cadeia de assinatura utilizando o seu segredo de webhook
5. Compare (com tempo constante) com a assinatura recebida
6. Rejeite se o timestamp tiver mais de 5 minutos de antiguidade (protecção contra repetição)

Exemplos de código

PHP

function verifyConsentForgeWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    // Rejeitar se for demasiado antigo (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 num 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) {
  // Rejeitar se for demasiado antigo (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 em 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);
  // processar payload...
  res.json({ received: true });
});

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Rejeitar se for demasiado antigo (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 em 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()
    # processar payload...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Rejeitar se for demasiado antigo (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 em 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)
    # processar payload...
    head :ok
  end
end

Idempotência

Utilize X-ConsentForge-Delivery-ID para desduplicar entregas repetidas. Armazene os IDs de entrega processados e salte os duplicados.

Rotação de segredo

Para rodar o seu segredo de webhook:

1. Gere um novo segredo no Painel (o segredo antigo permanece activo durante 24h)
2. Actualize o seu servidor para utilizar o novo segredo
3. Após 24h, o segredo antigo é invalidado