Webhookbeveiliging

Elk webhookverzoek van ConsentForge bevat een HMAC-SHA256-handtekening. Verifieer deze handtekening voordat u de payload verwerkt om te zorgen dat het verzoek echt is en niet is gemanipuleerd.

Verzoekheaders

Header	Beschrijving
X-ConsentForge-Signature	HMAC-SHA256 hex-samenvatting van {timestamp}.{body}
X-ConsentForge-Timestamp	Unix-tijdstempel (seconden) wanneer de gebeurtenis werd verzonden
X-ConsentForge-Delivery-ID	Unieke ID voor deze aflevering (gebruik voor idempotentie)

Verificatiealgoritme

1. Lees X-ConsentForge-Timestamp uit de verzoekheader
2. Lees X-ConsentForge-Signature uit de verzoekheader
3. Bouw de ondertekeningsstring: {timestamp}.{ruwe_verzoektekst}
4. Bereken HMAC-SHA256 van de ondertekeningsstring met uw webhookgeheim
5. Vergelijk (tijdveilig) met de ontvangen handtekening
6. Weiger als het tijdstempel meer dan 5 minuten oud is (bescherming tegen replay-aanvallen)

Codevoorbeelden

PHP

function verifyConsentForgeWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    // Weigeren als te oud (5 minuten)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }

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

    return hash_equals($expected, $signature);
}

// Gebruik in een 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) {
  // Weigeren als te oud (5 minuten)
  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')
  );
}

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

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Weigeren als te oud (5 minuten)
    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)

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

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Weigeren als te oud (5 minuten)
  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

# Gebruik 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)
    # payload verwerken...
    head :ok
  end
end

Idempotentie

Gebruik X-ConsentForge-Delivery-ID om opnieuw geprobeerde afleveringen te dedupliceren. Sla verwerkte afleverings-ID's op en sla duplicaten over.

Geheimsrotatie

Om uw webhookgeheim te roteren:

1. Genereer een nieuw geheim in het Dashboard (oud geheim nog 24 uur actief)
2. Werk uw server bij om het nieuwe geheim te gebruiken
3. Na 24 uur wordt het oude geheim ongeldig