​

Webhook-Sicherheit

​

Signaturüberprüfung

• Die Signatur ist der HMAC-SHA256 des unveränderten Anfragekörpers (genau so, wie er empfangen wurde), kodiert als Hexadezimalzeichenkette in Kleinbuchstaben (64 Zeichen). Es gibt kein Präfix wie sha256=.
• Der Schlüssel ist das webhook_secret, das Sie bei der Registrierung des Abonnements erhalten haben, als UTF-8-Zeichenkette genau so verwendet, wie es zurückgegeben wurde. Dekodieren Sie es nicht.
• Jedes Abonnement (Ziel-URL, Ereignistyp und Apotheken-Zuordnung) hat ein eigenes webhook_secret. Wenn Sie mehrere Ereignistypen am selben Endpoint empfangen, wählen Sie anhand des Headers X-Webhook-Event das Secret des passenden Abonnements.
• Es gibt keinen separaten Zeitstempel-Header. Das Feld timestamp im Anfragekörper ist durch die Signatur abgedeckt.

​

Beispiel (Python)

import hashlib
import hmac


def verify_webhook(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    # raw_body: der Anfragekörper genau so, wie er empfangen wurde, z. B. request.get_data() in Flask
    if not signature:
        return False
    expected = hmac.new(
        webhook_secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​

Beispiel (Node.js)

const crypto = require('crypto');

// rawBody: der Anfragekörper als Buffer, genau so, wie er empfangen wurde,
// z. B. mit express.raw({ type: 'application/json', limit: '10mb' })
function verifyWebhook(rawBody, signature, webhookSecret) {
  if (typeof signature !== 'string') {
    return false;
  }
  const expected = Buffer.from(
    crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex'),
  );
  const received = Buffer.from(signature);
  return expected.length === received.length
    && crypto.timingSafeEqual(expected, received);
}

​

Webhook-Secret

• Das webhook_secret wird nur einmal zurückgegeben: in der Antwort auf POST /v1/external_pharmacy_api/webhooks/ oder im Apothekenportal direkt nach der Registrierung eines Webhooks. Es wird verschlüsselt gespeichert und kann später nicht abgerufen werden — GET /v1/external_pharmacy_api/webhooks/ gibt es nie zurück.
• Jedes Abonnement hat ein eigenes Secret. X-Webhook-Event nennt den Ereignistyp einer Zustellung, aber nichts identifiziert das Abonnement selbst. Abonnements mit demselben Ereignistyp — zum Beispiel eines pro Apotheke einer Gruppe — lassen sich daher nicht unterscheiden. Verwenden Sie für diese jeweils eine eigene Ziel-URL (zum Beispiel einen anderen Pfad oder Query-Parameter), damit Sie immer wissen, mit welchem Secret Sie prüfen müssen.
• Auch der Wert eines benutzerdefinierten Headers (header_value) wird nie zurückgegeben, nur sein Name (header_key).

​

Secret rotieren

​

Best Practices