Webhooks und ereignisbasierte Integration: HMAC, Idempotency, Retry

Was sind Webhooks?

Ein Webhook ist eine ereignisbasierte HTTP-Schnittstelle: Ein Quell-System (Sender) ruft eine vorab konfigurierte URL beim Empfänger-System auf, sobald ein bestimmtes Ereignis eintritt. Statt dass der Empfänger regelmässig nachfragt (Polling), wird er aktiv benachrichtigt (Push). Die Nutzlast ist typischerweise JSON, der Transport HTTPS POST.

Ein klassisches Beispiel aus der CH-Treuhand-Welt: Stripe sendet einen Webhook payment_intent.succeeded, sobald ein Mandant eine Online-Zahlung erfolgreich abgeschlossen hat. Statt Ihr System alle 5 Minuten Stripe abzufragen, ob neue Zahlungen vorliegen, erhalten Sie die Information in Sekundenschnelle. Ein zweites Beispiel: Bexio sendet einen Webhook invoice.paid, sobald eine Mandanten-Rechnung als bezahlt markiert wird. Ihr System kann sofort eine Dankes-Mail oder eine Verbuchung in der Lohnbuchhaltung anstossen.

Webhooks haben drei zentrale Schwierigkeiten: Authentifizierung, Idempotency, und Zustellungs-Garantien. Erstens: Wer hat den Webhook gesendet? Wenn die URL bekannt ist, könnte jemand bösartige Requests faelschen. Lösung: HMAC-Signaturen. Der Sender berechnet aus Payload + geheimem Shared-Secret einen Hash und sendet ihn im Header X-Signature. Der Empfänger berechnet denselben Hash und vergleicht.

Zweitens: Idempotency. Webhooks können mehrfach gesendet werden, z.B. bei Retry nach Timeout. Wenn Ihr Empfänger einen Webhook zweimal verarbeitet, kann das eine doppelte Verbuchung oder eine doppelte Mail bedeuten. Lösung: Idempotency-Keys. Der Sender sendet einen eindeutigen Event-ID-Header, der Empfänger speichert die schon verarbeiteten IDs in einer DB und ignoriert Duplikate.

Drittens: Zustellungs-Garantien. Webhooks können verloren gehen (Netzwerk-Probleme, Empfänger-Ausfall). Robuste Sender implementieren Exponential Backoff (1s, 2s, 4s, 8s, ..., bis zu 24h) und sammeln nicht zustellbare Events in einer Dead-Letter-Queue. Robuste Empfänger sollten alle Webhooks innerhalb von 30 Sekunden mit 2xx beantworten, sonst gilt der Webhook als gescheitert.

Warum es für CH-Treuhand wichtig ist

Ein durchschnittliches Treuhand-Setup hat 8 bis 15 integrierte Systeme: Bexio oder Abacus, Banking (CAMT.053-Import), Stripe, Microsoft 365 oder Google Workspace, ein Mandanten-CRM, ein Time-Tracker, eine KI-Schicht. Wenn alle diese Systeme via Polling integriert sind, entstehen pro Tag tausende Polling-Calls, die zu 99 Prozent keine neuen Daten liefern.

Webhooks lösen das Problem auf drei Ebenen. Erstens: Geschwindigkeit. Ein Mandant zahlt seine Rechnung um 14:23, die Bestätigungs-Mail geht um 14:23:02 raus, statt erst im nächsten 5-Minuten-Polling-Lauf. Zweitens: API-Kosten. Bei Bexio sind Sie unter dem Rate-Limit von 50 Requests/Sekunde. Ohne Polling sparen Sie 70-95 Prozent der API-Calls. Drittens: Skalierbarkeit. Wenn die Mandantenzahl wächst, wächst der Polling-Aufwand linear. Webhooks skalieren von selbst: kein Event, kein Call.

Für KI-Workflows sind Webhooks besonders wertvoll. Eine neue Mail trifft im Posteingang ein: Microsoft Graph sendet eine Change Notification, die KI-Triage startet sofort, der Sachbearbeiter sieht die priorisierte Mail in unter 30 Sekunden. Ein neues Dokument wird in SharePoint hochgeladen: Webhook triggert die OCR-Pipeline und das Dokument ist innerhalb von 2 Minuten im RAG-Index.

Wie es funktioniert

Eine produktions-fähige Webhook-Pipeline hat vier Bausteine: Endpoint, Signatur-Verifikation, Idempotency-Speicher, Verarbeitungs-Queue.

Der Endpoint ist eine HTTPS-URL, die POST-Requests akzeptiert. Wichtig: Antworten Sie schnell (in unter 30 Sekunden) mit 2xx. Die eigentliche Verarbeitung (KI-Call, Datenbank-Insert) erfolgt asynchron in einer Queue.

Signatur-Verifikation: Lesen Sie den Signatur-Header (z.B. Stripe-Signature, X-Bexio-Signature) und berechnen Sie den HMAC-SHA256 über den rohen Request-Body mit dem Shared-Secret. Vergleichen Sie konstant-zeitig (constant-time comparison), um Timing-Angriffe zu vermeiden. Beispiel in Node.js:

```javascript const crypto = require('crypto'); function verify(rawBody, signatureHeader, secret) { const expected = crypto.createHmac('sha256', secret) .update(rawBody) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signatureHeader) ); } ```

Idempotency-Speicher: Lesen Sie den Event-ID-Header und prüfen Sie eine Tabelle webhook_events. Wenn die ID schon vorhanden ist, antworten Sie sofort mit 200 OK und ignorieren das Event. Sonst speichern Sie die ID mit Zeitstempel und verarbeiten weiter.

Verarbeitungs-Queue: Statt den Webhook synchron zu verarbeiten, schreiben Sie den Event in eine Queue (Redis, RabbitMQ, AWS SQS, oder ein simples Postgres-mit-NOTIFY-Setup) und antworten dem Sender mit 200 OK. Ein Worker-Prozess holt sich Events aus der Queue und verarbeitet sie. Vorteile: Sender bekommt schnelle Antwort, Sie können Verarbeitungs-Fehler retryen, Sie können die Last unabhängig vom Webhook-Volume skalieren.

Best-Practices Mai 2026: HTTPS mit gültigem Zertifikat (keine self-signed), Webhooks nur über definierte Pfade (nicht /), Logs aller eingehenden Events für Debugging, Dead-Letter-Queue für nicht verarbeitbare Events, ein Monitoring-Dashboard für Eingangs-Rate und Fehler-Quote.

Webhook-Setup in 5 Schritten

1. 01Webhook-URL definieren (z.B. https://api.kanzlei.ch/webhooks/bexio), HTTPS-Zertifikat sicherstellen, Pfad nicht raten lassen.
2. 02Shared-Secret beim Sender konfigurieren, in einem Secrets-Manager beim Empfänger ablegen, niemals in den Code commiten.
3. 03Endpoint implementieren: rohen Body lesen, HMAC-Signatur prüfen, Idempotency-Key in der DB nachschlagen, in Queue schreiben, mit 200 OK antworten.
4. 04Worker-Prozess für Verarbeitung aufsetzen: aus Queue lesen, Geschäftslogik (KI-Call, Bexio-Update), bei Fehler in DLQ legen.
5. 05Monitoring einrichten: Anzahl eingehender Events pro Stunde, Fehler-Quote, DLQ-Tiefe, Alarm bei Anomalien.

Wann Webhooks einsetzen

Webhooks sind die richtige Wahl, wenn (a) der Quell-Service sie anbietet, (b) Ereignisse zeitnah verarbeitet werden sollen und (c) der Polling-Aufwand spürbar ist.

Konkrete Use-Cases in CH-Treuhand: Bexio webhook invoice.paid triggert Dankes-Mail und Lohnbuchhaltungs-Insert. Stripe webhook payment_intent.succeeded triggert Mandanten-Bestätigung und Bexio-Insert. Microsoft Graph Change Notification für neue Mails triggert KI-Triage. SharePoint Webhook für neue Dokumente triggert OCR und RAG-Indexierung. Sage 50 webhook bank-transaction-created triggert KI-Buchungs-Vorschlag.

Als Faustregel: Wenn Sie eine API mehr als 4-mal pro Stunde abfragen, lohnt sich der Wechsel auf Webhooks. Wenn Sie eine API alle paar Tage einmal abfragen, ist Polling oft einfacher.

Wann NICHT

Wenn der Quell-Service keine Webhooks anbietet, mussen Sie pollen. Beispiel: alte SOAP-APIs ohne Webhook-Layer (Abacus pre-2025.2, Sage pre-2026, SAP B1 ohne Add-On).

Wenn die Verarbeitungs-Latenz unkritisch ist (etwa Quartals-Reports), ist Webhook-Setup überdimensioniert. Ein nightly Cron-Job mit API-Polling ist hier günstiger und einfacher.

Wenn der Empfänger nicht öffentlich erreichbar ist (Hinter Firewall, kein Reverse-Tunnel), können Sie keine Webhooks empfangen. Lösungen: Cloudflare Tunnel, ngrok für Tests, oder ein Webhook-Relay-Service.

Für Mandate mit sehr sensiblen Daten (etwa Berufsgeheimnis-Mandate) muss der Webhook-Endpoint zusätzlich abgesichert sein: IP-Whitelisting des Senders, mTLS (Mutual TLS) statt nur HTTPS, ein separater Netzwerk-Segment für den Empfänger.

Vor- und Nachteile

Häufige Fragen

Verwandte Themen

Quellen

1. Stripe Docs: Webhook signing and best practices · 2026-05
2. Microsoft Graph: change notifications guidance (May 2026) · 2026-05
3. OWASP: HMAC and constant-time comparison guidance · 2026-04
4. AWS Architecture: Dead-letter queue patterns 2026 · 2026-03