Webhook-Sicherheit

Jede Webhook-Anfrage von ConsentForge enthält eine HMAC-SHA256-Signatur. Überprüfen Sie diese Signatur, bevor Sie den Payload verarbeiten, um sicherzustellen, dass die Anfrage echt ist und nicht manipuliert wurde.

Anfrage-Header

Header	Beschreibung
X-ConsentForge-Signature	HMAC-SHA256-Hex-Digest von {timestamp}.{body}
X-ConsentForge-Timestamp	Unix-Zeitstempel (Sekunden), wann das Ereignis gesendet wurde
X-ConsentForge-Delivery-ID	Eindeutige ID für diese Zustellung (zur Idempotenz verwenden)

Überprüfungsalgorithmus

1. X-ConsentForge-Timestamp aus dem Anfrage-Header lesen
2. X-ConsentForge-Signature aus dem Anfrage-Header lesen
3. Den Signatur-String erstellen: {timestamp}.{raw_request_body}
4. HMAC-SHA256 des Signatur-Strings mit Ihrem Webhook-Geheimnis berechnen
5. (Timing-sicher) mit der empfangenen Signatur vergleichen
6. Ablehnen, wenn der Zeitstempel mehr als 5 Minuten alt ist (Replay-Schutz)

Codebeispiele

PHP

function verifyConsentForgeWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    // Ablehnen wenn zu alt (5 Minuten)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }

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

    return hash_equals($expected, $signature);
}

// Verwendung in einem 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) {
  // Ablehnen wenn zu alt (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')
  );
}

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

Python

import hmac
import hashlib
import time

def verify_consentforge_webhook(raw_body, signature, timestamp, secret):
    # Ablehnen wenn zu alt (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)

# Verwendung 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 verarbeiten...
    return {'received': True}

Ruby

require 'openssl'
require 'rack/utils'

def verify_consentforge_webhook(raw_body, signature, timestamp, secret)
  # Ablehnen wenn zu alt (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

# Verwendung 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 verarbeiten...
    head :ok
  end
end

Idempotenz

Verwenden Sie X-ConsentForge-Delivery-ID, um wiederholte Zustellungen zu deduplizieren. Speichern Sie verarbeitete Zustellungs-IDs und überspringen Sie Duplikate.

Geheimnis rotieren

So rotieren Sie Ihr Webhook-Geheimnis:

1. Generieren Sie ein neues Geheimnis im Dashboard (altes Geheimnis ist noch 24 Stunden aktiv)
2. Aktualisieren Sie Ihren Server auf das neue Geheimnis
3. Nach 24 Stunden wird das alte Geheimnis ungültig