AI translation
This page was translated from German with AI. If in doubt, the German original applies.
Webhooks and event notification¶
There is currently no push channel
ZEDAL does not actively notify your application when a new DIWASS response arrives. There is no webhook endpoint you can register, no event stream you can subscribe to and no long polling.
This is not a gap in this documentation: the mechanism has not been decided yet. That is also why there is no date and no commitment here — plan your integration as this page describes, not around a future channel.
How you learn about a change is therefore decided on the pull path. This page explains what that means for the design of your application. The operating rules themselves — sequential calls, event list, inbox import, synchronization frequency — are documented in one place and are not repeated here: Calls and synchronization.
What is possible today¶
| Path | With | What it does |
|---|---|---|
| Query the event list | DiwassApi.RetrievalApi.LookupEventList |
Returns, for a time window, what kind of change happened to which document. The mandatory first step of every synchronization. |
| Targeted reload | in the SDK handler.LoadFromZedalByNotificationId(…), LoadFromZedalByMovementId(…), ReloadFromZedal(); on the DIWASS side RetrievalApi.GetAllMovements and RetrievalApi.LookupSyncNotification |
Fetches only the documents for which the list names an event. Which operation belongs to which event is shown in the mapping under Retrieving changes. |
| Import incoming documents | CoreApi.Documents.ImportTransportDocumentFromInbox / ImportDocumentToFileAreaFromInbox, in the SDK DocumentHandler.CreateInboxImporter() |
The delivery path for changes from outside. Without this step, the new version does not appear in your inventory. |
| Wait for an expected result | handler.WaitUntil(condition, timeout, pollInterval) |
Local wait loop in the SDK for a process you have just triggered yourself. Not a substitute for synchronization. |
No full export as a substitute for push
The obvious workaround — “then I’ll just reload everything regularly” — is expressly prohibited. The Commission requires an event list plus targeted detail retrieval and reserves the right to block API access in case of continued violations. What exactly is required is described under Retrieving changes.
No streaming substitute in the contract¶
The proto contract contains no subscribe, watch or notify operation for document events. This also rules out the idea of attaching to an existing server stream:
- REST/JSON is unary — one request, one response. No server streaming, not even as Server-Sent Events. See REST / JSON → Streaming.
- gRPC and gRPC-Web support server streaming — but there is no stream you could subscribe to for notification, movement and Annex VII events.
Intervals that match the processing time¶
The waiting times follow from a measured value: a change from outside — a request for additional information from an authority, a decision, a response to a request for change — takes 100 to 150 seconds to show up in the ZEDAL inventory. Within this window, a reload returns the previous state. This looks like “nothing happened” and means “not there yet”.
| Situation | Approach |
|---|---|
| Directly after your own push | First wait for the transfer status to complete (WaitForDiwassTransfer), then check for the business response no earlier than about 2 to 3 minutes later. Checking earlier only costs calls. |
| Waiting cycle for an expected business response | Poll interval of 15 to 60 seconds, with an overall time limit that fits the process — multi-stage movement chains need several minutes per stage. Guideline values: Lifecycle → Sending procedure. |
| Regular synchronization as a safety net underneath | A cycle well under 12 hours, date_from set to the last successful synchronization, windows slightly overlapping. The 12 hours are a minimum requirement from the Implementing Regulation, not a recommendation. |
| No process open | Do not poll. The absence of a rate limit is not an invitation; what is required is “only when necessary and without duplicates”. |
A missing authority block is not a finding
A test or state check immediately after the other side’s push reliably produces a false failure: empty intent list, no authority block, document apparently unchanged. Never treat this state as final — and certainly do not conclude from it that a process was rejected.
What this means for the architecture¶
As long as the notification mechanism is undecided, the trigger side of your integration should remain interchangeable:
- Separate trigger and processing. Write a synchronization routine that processes a time period — fetch the event list, import the inbox, read the affected documents. Whatever calls it (timer, follow-up to your own push, user interface) does not belong in the same function. If a push channel arrives later, it calls the same routine.
- Persist the synchronization state. Time of the last successful synchronization plus the mapping DIWASS identifier ↔ local object. Without this mapping, events cannot be resolved, and incremental synchronization is impossible.
- Make synchronization idempotent. Overlapping time windows and repeated runs are the norm, not the exception.
- Expect unknown event codes. The codes are tokens, not a generated enum. A new code must not abort your synchronization; it belongs in follow-up handling.
- Design synchronization as a background process. Run times are in the range of minutes, and the calls must be made sequentially. There is no room for this in the request cycle of a web interface.
When something changes¶
As soon as a notification mechanism has been decided, it will be described here and in the Changelog. Until then: no push, no registration, no signature scheme to implement.
Next¶
- Calls and synchronization — the binding operating rules for synchronization and call rate
- Lifecycle — which response comes in which phase and how long it takes
- Storage areas — what distinguishes the inbox from the other areas
- .NET SDK —
WaitUntil,WaitForDiwassTransfer, inbox importer