Webhooks und Ereignisse

Ein Webhook ist ein systemischer Benachrichtigungsdienst, der die asynchrone Integration zwischen Systemen ermöglicht — Unico IDCloud benachrichtigt Ihr Backend, sobald ein Prozess seinen Zustand ändert, sodass Sie nicht regelmäßig nach Updates abfragen müssen.

Dieser Abschnitt behandelt die vier Dinge, die Sie für die Webhook-Integration benötigen: die Einrichtung des Endpunkts und der Authentifizierung, die von Unico gesendeten Ereignisse, die Fallback-Strategie und die Sicherheits- und Zuverlässigkeitsmuster, die Ihr Endpunkt implementieren muss.

Wann Webhooks verwenden

Webhooks sind die empfohlene Methode, um über den Abschluss von Prozessen benachrichtigt zu werden. Sie sind besonders relevant für:

• Visuelle Abläufe (SDK / Web Redirect / iFrame) — um zu wissen, wann der Benutzer die Journey abgeschlossen hat.
• Asynchrone Web- & SDK-Abläufe — um benachrichtigt zu werden, wenn ein POST /client/v1/process auf der Seite von Unico abgeschlossen wird.
• Lang laufende Abläufe, die mehrere Funktionen kombinieren (z. B. Dokumentenanalyse + manuelle Prüfung). Webhooks werden nur im Terminalzustand (PROCESS_STATE_FINISHED) ausgelöst; es werden keine Zwischen-Fortschrittsereignisse zugestellt.

Webhooks ergänzen die GetProcess-Endpunkte, ersetzen sie aber nicht. Siehe Fallback.

In diesem Abschnitt

• Einrichtung — Endpunktregistrierung, Authentifizierungsmethoden (OAuth2, Basic, API-Schlüssel), Wiederholungseinstellungen.
• Ereignistypen — die von Unico gesendeten Ereignisse und die Payload-Struktur.
• Sicherheit — Idempotenz, Gleichzeitigkeitslimit und Fehlerrate.
• Fallback — wie das Prozessergebnis abgerufen wird, wenn der Webhook nicht verfügbar ist.