Zum Inhalt

Webhooks und Event-Benachrichtigung

Es gibt heute keinen Push-Kanal

ZEDAL benachrichtigt deine Anwendung nicht aktiv, wenn eine neue DiWaSS-Antwort eintrifft. Es gibt keinen Webhook-Endpunkt, den du registrieren kannst, keinen Event-Stream, den du abonnieren kannst, und kein Long-Polling.

Änderungen fragst du ab; wie das geht, beschreibt diese Seite.

Wie du eine Änderung erfährst, entscheidet sich damit auf dem Abhol-Weg. Diese Seite sagt, was das für den Aufbau deiner Anwendung bedeutet. Die Betriebsregeln selbst — Sequenzialität, Ereignisliste, Inbox-Import, Abgleichhäufigkeit — stehen an einer Stelle und werden hier nicht wiederholt: Aufrufe und Synchronisation.

Was heute möglich ist

Weg Womit Was er leistet
Ereignisliste abfragen DiwassApi.RetrievalApi.LookupEventList Liefert für ein Zeitfenster, welche Art von Änderung an welchem Dokument passiert ist. Der vorgeschriebene erste Schritt jedes Abgleichs.
Gezielt nachladen im SDK handler.LoadFromZedalByNotificationId(…), LoadFromZedalByMovementId(…), ReloadFromZedal(); auf der DiWaSS-Seite RetrievalApi.GetAllMovements und RetrievalApi.LookupSyncNotification Holt nur die Dokumente, für die die Liste ein Ereignis nennt. Welche Operation zu welchem Ereignis gehört, steht in der Zuordnung unter Änderungen abholen.
Eingänge übernehmen CoreApi.Documents.ImportTransportDocumentFromInbox / ImportDocumentToFileAreaFromInbox, im SDK DocumentHandler.CreateInboxImporter() Der Zustellweg für Änderungen von außen. Ohne diesen Schritt erscheint die neue Version nicht in deinem Bestand.
Auf ein erwartetes Ergebnis warten handler.WaitUntil(condition, timeout, pollInterval) Lokale Warteschleife im SDK für einen Vorgang, den du gerade selbst ausgelöst hast. Kein Ersatz für den Abgleich.

Kein Vollabzug als Ersatz für Push

Der naheliegende Ausweg — „dann lade ich eben alles regelmäßig neu” — ist ausdrücklich untersagt. Die Kommission verlangt Ereignisliste plus gezielten Detailabruf und behält sich bei fortgesetzten Verstößen die Sperrung des API-Zugangs vor. Was genau gefordert ist, steht unter Änderungen abholen.

Kein Streaming-Ersatz im Vertrag

Der Proto-Vertrag führt keine Subscribe-, Watch- oder Notify-Operation für Dokument-Ereignisse. Damit fällt auch die Idee weg, sich an einen bestehenden Server-Stream zu hängen:

  • REST/JSON ist unary — eine Anfrage, eine Antwort. Kein Server-Streaming, auch nicht als Server-Sent Events. Siehe REST / JSON → Streaming.
  • gRPC und gRPC-Web können Server-Streaming — es gibt für Notifizierungs-, Movement- und Annex-VII-Ereignisse aber keinen Stream, den man abonnieren könnte.

Intervalle, die zur Laufzeit passen

Die Wartezeiten ergeben sich aus der Laufzeit: Rechne bei einer Änderung von außen — Nachforderung einer Behörde, Entscheidung, Antwort auf einen Änderungsantrag — mit zwei bis drei Minuten, bis sie im ZEDAL-Bestand auftaucht. In diesem Fenster liefert ein Nachladen den Ausgangsstand. Das sieht aus wie „nichts passiert” und heißt „noch nicht da”.

Situation Vorgehen
Direkt nach einem eigenen Push Erst den Übermittlungsstatus abschließen (WaitForDiwassTransfer), dann frühestens rund 2 bis 3 Minuten später auf die fachliche Antwort prüfen. Früher zu prüfen kostet nur Aufrufe.
Wartezyklus auf eine erwartete fachliche Antwort Poll-Intervall 15 bis 60 Sekunden, mit einer Gesamt-Zeitgrenze, die zum Vorgang passt — mehrstufige Movement-Ketten brauchen pro Stufe mehrere Minuten. Richtwerte: Lebenszyklus → Versandverfahren.
Regelmäßiger Abgleich als Netz darunter Ein Zyklus deutlich unter 12 Stunden, date_from auf den letzten erfolgreichen Abgleich, Fenster leicht überlappend. Die 12 Stunden sind eine Untergrenze aus der Durchführungsverordnung, keine Empfehlung.
Kein Vorgang offen Nicht pollen. Die Abwesenheit eines Rate-Limits ist keine Einladung; gefordert ist „nur wenn erforderlich und ohne Duplikate”.

Ein fehlender Behörden-Block ist kein Befund

Eine Zustandsprüfung unmittelbar nach dem Push der Gegenseite schlägt zuverlässig falsch fehl: leere Intent-Liste, kein Behörden-Block, Dokument scheinbar unverändert. Bewerte diesen Zustand nie als endgültig — und leite daraus schon gar nicht ab, dass ein Vorgang abgelehnt wurde.

Was das für die Architektur heißt

Halte die Auslöser-Seite deiner Integration austauschbar:

  • Trenne Auslöser und Verarbeitung. Schreib eine Abgleich-Routine, die einen Zeitraum verarbeitet — Ereignisliste holen, Inbox importieren, betroffene Dokumente lesen. Wer sie aufruft (Timer, Nachlauf zu einem eigenen Push, Bedienoberfläche), gehört nicht in dieselbe Funktion.
  • Führe den Abgleichsstand persistent. Zeitpunkt des letzten erfolgreichen Abgleichs plus die Zuordnung DiWaSS-Kennung ↔ lokales Objekt. Ohne diese Zuordnung sind Ereignisse nicht auflösbar, und ein inkrementeller Abgleich ist unmöglich.
  • Mach den Abgleich idempotent. Überlappende Zeitfenster und wiederholte Läufe sind der Normalfall, nicht die Ausnahme.
  • Rechne mit unbekannten Ereignis-Codes. Die Codes sind Token, keine generierte Enum. Ein neuer Code darf deinen Abgleich nicht abbrechen, sondern gehört in die Nacharbeit.
  • Plane den Abgleich als Hintergrundprozess. Die Laufzeiten liegen im Minutenbereich und die Aufrufe müssen sequenziell erfolgen. Im Request-Zyklus einer Weboberfläche hat das keinen Platz.

Wenn sich etwas ändert

ZEDAL bietet derzeit keinen Push-Kanal an; Änderungen fragst du ab (siehe Was heute möglich ist). Es gibt nichts zu registrieren und kein Signatur-Verfahren zu implementieren. Neuerungen stehen im Changelog.

Weiter