Webhooks sicher verarbeiten

Webhooks melden freigegebene Ereignisse asynchron. Registrieren Sie nur einen öffentlichen HTTPS-Endpunkt und verwenden Sie die Testzustellung, bevor Sie die Integration aktiv überwachen.

Zustellpfad

flowchart LR
  accTitle: Zustellpfad eines signierten Webhooks
  Transaction[Fachliche Transaktion] --> Outbox[Transaktionale Outbox]
  Outbox --> Dispatcher[Webhook Dispatcher]
  Dispatcher --> Signed[Signierte HTTPS-Zustellung]
  Signed --> Receiver[Partner-Endpunkt]
  Receiver -->|2xx| Done[Zustellung bestätigt]
  Receiver -->|Fehler oder Timeout| Retry[Begrenzter Retry]
  Retry --> Dispatcher
  Retry -->|Wiederholt fehlgeschlagen| DeadLetter[Fehlerwarteschlange und Alarm]

HMAC verifizieren

Bei der HMAC-Variante wird das Secret genau einmal bei der Registrierung zurückgegeben. Speichern Sie es unmittelbar in einem Secret Store. Berechnen Sie für jede Zustellung HMAC-SHA256 über die Bytefolge aus x-akflow-timestamp, einem Punkt und dem unveränderten HTTP-Body. Vergleichen Sie das Ergebnis in konstanter Zeit mit x-akflow-signature.

signed_payload = x-akflow-timestamp + "." + raw_request_body
expected       = HMAC-SHA256(webhook_secret, signed_payload)

Parsen oder formatieren Sie JSON erst nach erfolgreicher Signaturprüfung. Geben Sie zügig einen 2xx-Status zurück und verarbeiten Sie das Ereignis anschließend aus Ihrer eigenen Queue.

Idempotenz und Fehlerfälle

• Deduplizieren Sie Zustellungen anhand der stabilen Ereignis- oder Idempotenzkennung aus dem veröffentlichten Vertrag.
• Wiederholte Zustellungen müssen dasselbe Ergebnis erzeugen und dürfen keine zweite fachliche Aktion auslösen.
• Antworten Sie nur nach erfolgreicher Annahme mit 2xx; Timeouts und andere Statuscodes können erneut zugestellt werden.
• Alarmieren Sie bei anhaltenden Signaturfehlern, Rückständen und wiederholten Zustellfehlern.
• Protokollieren Sie keine Secrets, vollständigen Payloads oder personenbezogenen Inhalte.