Warum Polling auf Signaturstatus scheitert
Die meisten Signatur-Integrationen beginnen mit einem Schleifenaufruf. Ein Hintergrundjob fragt alle paar Minuten bei der API nach, ob ein Dokument signiert ist, und aktualisiert dann den Status im eigenen System. Für den Prototyp funktioniert das, für den Betrieb nicht. Webhook State Management ersetzt diese Schleife durch eine Umkehrung der Zuständigkeit: Die Signaturstrecke meldet Zustandswechsel aktiv, und Ihr System verarbeitet sie als Ereignisse. Das klingt nach einem technischen Detail und ist doch eine der folgenreichsten Architekturentscheidungen in einer Signaturintegration.
Polling hat drei strukturelle Probleme. Das erste ist Last ohne Information. Bei tausend offenen Vorgängen und einem Abfrageintervall von fünf Minuten erzeugen Sie Tausende Anfragen, von denen die meisten „nichts Neues“ melden. Das belastet Ihre Infrastruktur, die API des Anbieters und Ihre Ratenbegrenzungen, und es skaliert schlecht, wenn Ihre Mandantenzahl wächst. Das zweite ist Latenz. Wenn ein Vertrag um 10:01 Uhr signiert wird und Ihr Job um 10:05 Uhr fragt, sieht der Nutzer vier Minuten lang einen veralteten Stand. In Prozessen, die an der Signatur hängen, etwa Freigaben oder Bereitstellungen, ist das spürbar.
Das dritte Problem ist Inkonsistenz. Polling erzeugt Momentaufnahmen, keine Historie. Wenn ein Vorgang zwischen zwei Abfragen den Zustand zweimal wechselt, etwa von „geöffnet“ über „abgelehnt“ zu „neu gestartet“, sehen Sie nur das Ende. Für Audit und Fehleranalyse fehlt die Geschichte, und für fachliche Folgeprozesse fehlen die Auslöser. Wie wichtig diese Geschichte für Nachweise ist, zeigt der Beitrag DORA Artikel 30 und der API-Audit-Trail, der Ereignisse als Evidence behandelt.
Webhooks lösen diese Probleme, bringen aber eigene Anforderungen mit. Sie machen Ihr System zum Empfänger, der jederzeit Nachrichten annehmen muss, auch doppelte, verspätete oder ungeordnete. Wer Webhooks wie einen einfachen Funktionsaufruf behandelt, tauscht die Probleme des Pollings gegen subtilere Fehler: doppelt ausgelöste Folgeprozesse, verlorene Ereignisse bei Ausfällen, Zustände, die rückwärts springen. Die Kunst liegt darin, ein Zustandsmodell zu bauen, das mit der Unvollkommenheit der Zustellung umgehen kann.
Die eine harte Unterscheidung dieses Beitrags lautet deshalb: Ein Webhook ist ein Hinweis, kein Befehl. Er sagt Ihnen, dass sich etwas geändert hat. Ob und wie Ihr System darauf reagiert, entscheidet Ihr Zustandsmodell, nicht die Reihenfolge der eingehenden Nachrichten. Wer diesen Satz verinnerlicht, vermeidet die meisten klassischen Fehler. Für den Einstieg in die Praxis finden Sie Dokumentation und Sandbox im Developer Hub, und wie Webhooks im Kontext einer nativen Strecke wirken, beschreibt White-label Signatur ohne Medienbruch.
Es gibt Fälle, in denen Polling als Ergänzung sinnvoll bleibt, nämlich als Abgleich. Ein täglicher Job, der offene Vorgänge gegen den Stand der API prüft, fängt verlorene Ereignisse auf und dient als Sicherheitsnetz. Der Unterschied zum reinen Polling-Ansatz: Der Abgleich ist die Ausnahme und nicht der Hauptweg. Er läuft selten, belastet die Systeme kaum und liefert eine Kontrollinstanz, die Sie in Audits als Beleg für Ihre Sorgfalt nutzen können.
Ereignistypen und ihr Zustandsmodell
Bevor Sie Code schreiben, brauchen Sie ein Modell. Ein Signaturvorgang durchläuft Zustände, und Webhooks signalisieren die Übergänge. Die genauen Ereignisnamen entnehmen Sie der Dokumentation im Developer Hub. Konzeptionell lassen sich die Ereignisse in vier Gruppen einteilen, die Sie in Ihrem System unterschiedlich behandeln sollten.
Lebenszyklus-Ereignisse markieren den Verlauf: Vorgang angelegt, Einladung versendet, Dokument geöffnet, Unterzeichner hat gehandelt, Vorgang abgeschlossen. Ergebnis-Ereignisse beschreiben das Resultat: signiert, abgelehnt, abgelaufen, widerrufen. Identifikations-Ereignisse belegen, dass ein Unterzeichner die erforderliche Prüfung durchlaufen hat, bei AES und QES besonders relevant. Fehler- und Statusereignisse melden Störungen: Zustellung fehlgeschlagen, Dokument nicht verarbeitbar, Partnerdienst nicht erreichbar.
Aus diesen Ereignissen bauen Sie in Ihrem System einen Zustandsautomaten. Jeder Vorgang hat einen aktuellen Zustand, und es gibt eine definierte Menge erlaubter Übergänge. Ein Vorgang kann von „versendet“ nach „geöffnet“ oder „abgelaufen“ wechseln, aber nicht von „abgeschlossen“ zurück nach „versendet“. Kommt ein Ereignis, das nach Ihrem Automaten keinen gültigen Übergang auslöst, ignorieren Sie es nicht stillschweigend, sondern protokollieren es als Anomalie. Oft ist das ein verspätetes Ereignis, das ein anderes bereits überholt hat, und manchmal ein echtes Problem.
Speichern Sie neben dem aktuellen Zustand die Ereignishistorie. Jede Zeile enthält Vorgangs-ID, Ereignistyp, Zeitpunkt des Ereignisses laut Quelle, Eingangszeit bei Ihnen, eine eindeutige Ereignis-ID und gegebenenfalls Nutzlast oder Referenz darauf. Mit dieser Historie können Sie Zustände rekonstruieren, Anomalien erklären und Nachweise liefern. Der aktuelle Zustand ist eine Ableitung der Historie, nicht umgekehrt. Diese Denkweise, Ereignisse als primäre Wahrheit zu behandeln, kommt aus dem Event-Sourcing und lässt sich in schlankerer Form auch ohne ein komplettes Framework anwenden.
Fachlich sollten Sie unterscheiden, welche Ereignisse Folgeprozesse auslösen. Typischerweise sind das nur wenige: Abschluss, Ablehnung und Ablauf. Alle anderen dienen der Anzeige und dem Nachweis. Diese Trennung verhindert, dass ein verspätetes „Dokument geöffnet“ versehentlich eine Freigabe auslöst. Definieren Sie pro auslösendem Ereignis genau, was passiert und wie oft es höchstens passieren darf. Letzteres führt direkt zur Idempotenz.
Auch die Signaturstufe prägt das Modell. Bei einer einfachen Signatur (SES) ist der Weg kurz. Bei AES und QES kommen Identifikationsschritte hinzu, und bei QES arbeitet im Hintergrund ein Partner-QTSP wie Sign8, da Sign2x selbst kein QTSP ist. Ihr Automat sollte diese Schritte als eigene Zustände oder Unterzustände abbilden, damit Sie für Nutzer verständliche Fortschrittsanzeigen bauen können. Einen Überblick über die Stufen bietet der Beitrag SES, AES und QES in SaaS, und wie der Weg zur ersten QES-Strecke aussieht, steht in Von der Sandbox zur ersten QES-Strecke.
Idempotenz, Reihenfolge und Retries
Webhook-Zustellung ist grundsätzlich mindestens einmal: Die Quelle versucht so lange, bis sie eine Bestätigung erhält, und das kann zu Duplikaten führen. Netzwerke sind unzuverlässig, Antworten gehen verloren, und Absender wiederholen zur Sicherheit. Ihr Empfänger muss deshalb idempotent sein: Dieselbe Nachricht mehrfach zu verarbeiten darf dasselbe Ergebnis haben wie einmal. Der Begriff stammt aus der HTTP-Semantik (RFC 9110), und er gilt hier sinngemäß für Ihre Verarbeitungslogik.
Das praktische Muster ist einfach. Jedes Ereignis trägt eine eindeutige Kennung. Beim Eingang prüfen Sie, ob diese Kennung bereits in Ihrer Ereignishistorie steht. Wenn ja, bestätigen Sie den Empfang und tun nichts weiter. Wenn nein, schreiben Sie die Kennung und die Zustandsänderung in derselben Transaktion, sodass nie ein Zustand ohne Eintrag in der Historie existiert und umgekehrt. Eine Eindeutigkeitsbeschränkung in der Datenbank sichert diese Regel ab, auch wenn zwei Nachrichten gleichzeitig eintreffen.
Zur Reihenfolge: Gehen Sie nie davon aus, dass Ereignisse in der Reihenfolge ihres Entstehens ankommen. Zwei Webhooks können sich überholen, besonders bei Wiederholungen nach Ausfällen. Prüfen Sie deshalb gegen Ihren Zustandsautomaten und verwenden Sie den Ereigniszeitpunkt der Quelle statt der Eingangszeit, wenn Sie entscheiden, welches Ereignis neuer ist. Bei Konflikten ist ein Nachfragen bei der API die sicherste Lösung: Sie lesen den aktuellen Stand des Vorgangs und gleichen ihn ab, statt aus der Reihenfolge der Nachrichten zu raten.
Beim Antworten gilt die Regel „schnell bestätigen, später verarbeiten“. Ihr Endpunkt sollte die Nachricht prüfen, in eine Warteschlange legen und sofort mit einem Erfolgscode antworten. Die eigentliche Verarbeitung, mit Datenbankzugriffen, Aufrufen an Fremdsysteme und Folgeprozessen, läuft asynchron. So vermeiden Sie Zeitüberschreitungen, die beim Absender Wiederholungen auslösen und die Duplikatquote erhöhen. Antworten Sie nur dann mit einem Fehlercode, wenn die Nachricht wirklich nicht angenommen werden konnte, damit eine Wiederholung sinnvoll ist.
Auf der Empfängerseite brauchen Sie auch eigene Retries. Wenn die Verarbeitung scheitert, weil Ihr ERP kurz nicht erreichbar ist, darf das Ereignis nicht verloren gehen. Legen Sie fehlgeschlagene Verarbeitungen in eine Wiederholungswarteschlange mit wachsendem Abstand und einer Obergrenze. Nach Erreichen der Obergrenze landet das Ereignis in einer Fehlerablage, die ein Mensch prüft. Wichtig ist, dass die Fehlerablage sichtbar ist: Ein Dashboard oder ein Alarm, der anschlägt, wenn dort etwas liegt, verhindert, dass stille Ausfälle wochenlang unentdeckt bleiben.
Zur Authentizität: Ein Webhook-Endpunkt ist von außen erreichbar, und jeder könnte versuchen, gefälschte Ereignisse zu senden. Prüfen Sie daher, dass die Nachricht tatsächlich von der Signaturstrecke stammt, etwa über Signaturen im Header oder ein gemeinsames Geheimnis, wie es die Dokumentation beschreibt. Begrenzen Sie die Größe der Nachrichten, validieren Sie das Schema, und verarbeiten Sie nur Felder, die Sie brauchen. Allgemeine Hinweise zur sicheren Gestaltung von Schnittstellen bietet das BSI.
ERP und CRM anbinden: vom Ereignis zum Fachprozess
Im Zentrum der Anbindung steht eine klare Übersetzung: Ein Ereignis der Signaturstrecke wird zu einer fachlichen Zustandsänderung im ERP oder CRM. „Vorgang abgeschlossen“ wird zu „Vertrag unterzeichnet“, und das löst im ERP vielleicht die Auftragsfreigabe aus, im CRM das Schließen einer Opportunity und im Dokumentenmanagement die Ablage des signierten Dokuments. Diese Übersetzung gehört in eine eigene Schicht, den Adapter, und nicht verstreut in den Fachmodulen.
Der Adapter hat drei Aufgaben. Er nimmt Ereignisse an, validiert sie und schreibt sie in die Historie. Er wendet den Zustandsautomaten an und ermittelt, ob ein fachlicher Folgeprozess fällig ist. Und er ruft die Fachsysteme über deren Schnittstellen auf, mit eigener Wiederholungslogik und Fehlerbehandlung. Weil die Fachsysteme oft langsamer und fehleranfälliger sind als die Signaturstrecke, entkoppelt der Adapter beide Seiten. Fällt das ERP für eine Stunde aus, stauen sich Ereignisse im Adapter und werden danach abgearbeitet, statt Webhooks zu verlieren.
Eine Schlüsselentscheidung ist die Referenz. Beim Anlegen des Vorgangs geben Sie Ihre eigenen Kennungen mit, etwa Vertragsnummer, Mandant und Belegtyp. Diese Referenzen kommen in den Webhooks zurück und erlauben die eindeutige Zuordnung zum Fachobjekt, ohne dass Sie Tabellen durchsuchen müssen. Bei mandantenfähigen Systemen ist die Mandantenkennung Pflicht, damit Ereignisse nie im falschen Mandanten landen. Mehr zu Mandantenmodellen lesen Sie in Whitelabel-Anforderungen für ISVs.
Für die Oberfläche empfiehlt sich ein optimistischer, aber ehrlicher Umgang mit Zuständen. Solange ein Nutzer in Ihrer Oberfläche signiert, zeigen Sie den Fortschritt, den Sie kennen. Wenn die Bestätigung per Webhook noch aussteht, zeigen Sie „wird verarbeitet“ statt eines vorschnellen „fertig“. Das verhindert, dass Nutzer ein Dokument für unterzeichnet halten, das fachlich noch nicht freigegeben ist. Für ERP-Oberflächen mit eingebetteter Signatur beschreibt der Beitrag Silent Tech: Signatur in ERP-Oberflächen weitere Muster.
Bei der Datenhaltung lohnt ein Blick auf Aufbewahrung und Datenschutz. Ereignisdaten enthalten Zeitpunkte, Rollen und Referenzen, manchmal personenbezogene Informationen. Legen Sie fest, wie lange Sie sie aufbewahren, und trennen Sie, was für den Nachweis nötig ist, von dem, was nur für den Betrieb gebraucht wird. Die rechtlichen Grundlagen liefert die DSGVO. Sign2x läuft auf der Open Sovereign Cloud (OSC) von T-Systems, was für Ihre Dokumentation zur Auftragsverarbeitung eine klare Standortaussage ermöglicht.
Für Bulk-Szenarien, bei denen viele Vorgänge gleichzeitig laufen, gilt dasselbe Modell, aber mit mehr Aufmerksamkeit für Durchsatz und Rückstau. Wie sich Muster für große Volumina gestalten lassen, ohne unbelegte Leistungszahlen zu versprechen, beschreibt der Beitrag Bulk-Signatur-API für Unternehmen. Die wichtigste Regel bleibt dieselbe: Entkoppeln Sie Annahme und Verarbeitung.
Typische Fehlerbilder und wie Sie sie erkennen
Aus der Praxis ergeben sich einige wiederkehrende Fehlerbilder. Das häufigste ist die Doppelverarbeitung: Ein Abschluss-Ereignis löst zweimal denselben Folgeprozess aus, etwa zwei Rechnungen oder zwei Freigaben. Ursache ist fast immer fehlende Idempotenz oder eine Prüfung außerhalb der Transaktion. Erkennbar ist es an Duplikaten in den Fachdaten bei gleichzeitig einmaligem Vorgang. Abhilfe: Eindeutigkeitsbeschränkung auf der Ereignis-ID und Folgeprozesse an die Zustandsänderung koppeln, nicht an das Eintreffen einer Nachricht.
Das zweite Fehlerbild ist der Zustandssprung rückwärts. Ein verspätetes Ereignis überschreibt einen neueren Zustand, und ein bereits abgeschlossener Vorgang erscheint wieder als offen. Ursache ist ein Zustandsmodell ohne Übergangsprüfung. Abhilfe ist der Automat mit erlaubten Übergängen und der Abgleich über die API im Zweifel. Das dritte ist das verlorene Ereignis: Ihr Endpunkt war während einer Wartung nicht erreichbar, und niemand hat es bemerkt. Abhilfe sind der tägliche Abgleich, Alarme bei Fehlern und eine Fehlerablage, die jemand beobachtet.
Das vierte Fehlerbild ist der Zeitüberschreitungs-Kreislauf. Ihr Endpunkt verarbeitet synchron, antwortet zu langsam, der Absender wiederholt, und die Last wächst. Abhilfe ist schnelles Bestätigen und asynchrones Verarbeiten. Das fünfte ist der Mandantenfehler: Ein Ereignis landet im falschen Mandanten, weil die Referenz fehlte oder ungenau war. Das ist ein Datenschutzvorfall und gehört in jeden Test. Prüfen Sie gezielt, dass ein Ereignis mit unbekannter oder nicht zugeordneter Referenz abgelehnt und gemeldet wird.
Zum Schluss ein Wort zu Beobachtbarkeit. Messen Sie Eingangsrate, Verarbeitungsdauer, Wiederholungsquote und Größe der Fehlerablage. Diese Kennzahlen zeigen, ob Ihre Integration gesund ist, lange bevor Nutzer sich beschweren. Wir nennen bewusst keine Referenzwerte, denn sie hängen von Ihrem Volumen und Ihren Fachsystemen ab. Wichtig ist, dass Sie Ihre eigene Baseline kennen und Abweichungen bemerken. Weitere Hilfen finden Sie im Help Center, Beispiele unter Use Cases und ergänzende Artikel im Sign2x Blog. Für eine erste Einordnung Ihrer Situation dient das Sign2x Quiz, und bei konkreten Fragen erreichen Sie uns über Kontakt.
Webhooks in der Sandbox testen
Weiterführend: White-label Signatur-API ohne Medienbruch und NIS-2 Nachweis über den Audit-Trail der Signatur. Die rechtlichen Grundlagen der Signaturstufen finden Sie in der eIDAS-Verordnung.
Häufige Fragen
Warum sind Webhooks besser als Polling für Signaturstatus?
Webhooks melden Zustandswechsel aktiv, sparen Last, senken Latenz und liefern eine Ereignishistorie statt Momentaufnahmen. Ein täglicher Abgleich bleibt als Sicherheitsnetz sinnvoll.
Was bedeutet Idempotenz bei Webhook-Empfängern?
Dieselbe Nachricht mehrfach zu verarbeiten darf dasselbe Ergebnis haben wie einmal. Praktisch speichern Sie die Ereignis-ID in einer Eindeutigkeitsbeschränkung und schreiben Zustand und Historie in einer Transaktion.
Wie gehe ich mit Ereignissen außer der Reihenfolge um?
Prüfen Sie jeden Übergang gegen einen Zustandsautomaten, nutzen Sie den Ereigniszeitpunkt der Quelle und gleichen Sie im Zweifel den aktuellen Stand per API ab.
Wie schnell sollte mein Endpunkt antworten?
So schnell wie möglich. Prüfen Sie die Nachricht, legen Sie sie in eine Warteschlange und bestätigen Sie sofort. Die Verarbeitung läuft asynchron, damit keine Zeitüberschreitungen Wiederholungen auslösen.
Welche Rolle spielt Sign2x bei QES?
Sign2x ist die API-Schicht und kein QTSP. Für QES läuft die Qualifikation über einen Partner-QTSP wie Sign8. Ihre Zustandsmodelle sollten die Zwischenschritte abbilden.
