Webhooks für die Lohnabrechnung: Lohnläufe event-getrieben verarbeiten
Ein Lohnlauf ist kein Ein-Klick-Moment, sondern ein Prozess mit Wartezeiten: Der Lauf wird festgeschrieben, Dokumente entstehen, Meldungen gehen raus — und ihre Bestätigung kommt erst später von den Annahmestellen zurück. Genau für solche asynchronen Abläufe sind Webhooks gemacht.
Auf einen Blick: Ein Webhook ist ein Callback: Statt den Status einer Payroll-API ständig abzufragen (Polling), schickt die API dir einen HTTP-POST, sobald ein Ereignis eintritt — Lauf festgeschrieben, Dokument erzeugt, Meldung übermittelt oder bestätigt. Das ist besonders in der Lohnabrechnung wichtig, weil die Meldungen an Sozialversicherung und Finanzamt zeitversetzt bestätigt werden. Robust wird es mit Signatur-Prüfung, Retries und Idempotenz.
Warum Webhooks statt Polling?
Polling heißt: „Ist es schon fertig? Und jetzt? Und jetzt?” — im Sekunden- oder Minutentakt nachfragen. Das ist verschwenderisch und trotzdem langsam. Webhooks drehen die Richtung um: Die API benachrichtigt dich, sobald sich etwas ändert. Kein Leerlauf, keine verpassten Zustände.
In der Payroll ist das kein Luxus. Die elektronischen Meldungen an die Sozialversicherung werden erst nach Verarbeitung durch die Annahmestellen quittiert — das automatisierte Meldeverfahren läuft nun einmal asynchron. Ein Webhook sagt dir zuverlässig Bescheid, wenn die Rückmeldung da ist.
Welche Ereignisse zählen
Typische Payroll-Events, auf die eine Integration reagiert:
lohnlauf.probe_berechnet— der Probelauf steht, Summen sind da.lohnlauf.festgeschrieben— der Lauf ist verbindlich, Dokumente entstehen.dokument.erstellt— Entgeltabrechnung, Buchungsstapel oder Zahldatei sind abrufbar.meldung.uebermittelt/meldung.bestaetigt— eine SV-/Steuer-Meldung ist raus bzw. quittiert.meldung.abgelehnt— eine Meldung wurde beanstandet und braucht Nacharbeit.
Wie ein Webhook technisch funktioniert
Du hinterlegst eine Endpoint-URL. Tritt ein Ereignis ein, schickt die API einen POST mit einem JSON-Payload (Event-Typ, Event-ID, Zeitstempel, betroffene Ressource) an diese URL. Dein Endpoint antwortet mit einem 2xx-Status, um den Empfang zu bestätigen. Bleibt die Bestätigung aus, versucht es die API erneut.
Robust bauen: Signatur, Retries, Idempotenz
Drei Dinge trennen eine belastbare Integration von einer wackligen:
- Signatur prüfen: Ein seriöser Anbieter signiert jeden Webhook (z. B. per HMAC-SHA256 im Header). Prüfe die Signatur, bevor du den Payload verarbeitest — sonst könnte jeder gefälschte Events einwerfen. Lohndaten sind zu sensibel für ungeprüfte Callbacks.
- Retries vertragen: Weil fehlgeschlagene Zustellungen wiederholt werden (meist mit exponentiellem Backoff), kann derselbe Event mehrfach ankommen. Antworte schnell mit 2xx und verarbeite die Arbeit asynchron.
- Idempotent verarbeiten: Speichere die Event-ID und ignoriere Duplikate. So löst ein doppelt zugestellter „festgeschrieben”-Event nicht zweimal deine Folgeaktion aus.
Ein Beispiel-Fluss
Deine Software startet einen Lauf und wartet nicht: Sie bekommt festgeschrieben, lädt die Dokumente
bei dokument.erstellt, und markiert den Monat als „gemeldet”, sobald meldung.bestaetigt eintrifft —
ohne einmal aktiv nachgefragt zu haben. Fällt eine Meldung mit meldung.abgelehnt zurück, öffnet sie
automatisch eine Aufgabe für die Sachbearbeitung.
Häufige Fragen
Was ist der Vorteil gegenüber Polling?
Kein Leerlauf und schnellere Reaktion: Die API meldet sich genau dann, wenn sich etwas ändert. Gerade bei den zeitversetzt bestätigten Meldungen ist das deutlich effizienter.
Wie stelle ich sicher, dass ein Webhook echt ist?
Über die Signatur: Prüfe den mitgeschickten HMAC gegen dein Webhook-Secret. Nur bei gültiger Signatur verarbeitest du den Payload.
Was mache ich bei doppelt zugestellten Events?
Idempotent verarbeiten — die Event-ID merken und Duplikate verwerfen. Retries sind normal; deine Logik muss sie vertragen.
Weiterführend
- Payroll API — Ressourcen, Idempotenz und Webhooks im Überblick
- API-Dokumentation für Entwickler — Einstieg und Beispiele
- Lohnabrechnung per API automatisieren — der Ablauf in vier Schritten
- Loslegen? Auf die Warteliste eintragen.