Webhook-beveiliging

Elk webhookverzoek van ConsentForge bevat een HMAC-SHA256-handtekening. Verifieer deze handtekening voor verwerking van de payload om te verzekeren dat het verzoek authentiek is en niet is gemanipuleerd.

Verzoekheaders

Header	Beschrijving
X-ConsentForge-Signature	HMAC-SHA256 hexadecimale samenvatting van {timestamp}.{body}
X-ConsentForge-Timestamp	Unix-tijdstempel (seconden) wanneer de gebeurtenis is verzonden
X-ConsentForge-Delivery-ID	Uniek ID voor deze levering (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}.{raw_request_body}
4. Bereken HMAC-SHA256 van de ondertekeningsstring met uw webhookgeheim
5. Vergelijk (tijdsveilig) met de ontvangen handtekening
6. Weiger als tijdstempel meer dan 5 minuten oud is (bescherming tegen replay-aanvallen)

Codevoorbeelden

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

Idempotentie

Gebruik X-ConsentForge-Delivery-ID om herhaalde leveringen te dedupliceren. Sla verwerkte levering-ID's op en sla duplicaten over.

Geheimrotatie

Om uw webhookgeheim te roteren:

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