Webhook-Sicherheit

Jede Webhook-Anfrage von ConsentForge enthält eine HMAC-SHA256-Signatur. Verifizieren Sie diese Signatur, bevor Sie das Payload verarbeiten, um sicherzustellen, dass die Anfrage authentisch 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) zum Zeitpunkt des Event-Versands
X-ConsentForge-Delivery-ID	Eindeutige ID für diese Zustellung (für Idempotenz verwenden)

Verifizierungsalgorithmus

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

Code-Beispiele

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

Idempotenz

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

Secret-Rotation

So rotieren Sie Ihr Webhook-Secret:

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