Einrichtung

Um einen Webhook in Unico IDCloud zu konfigurieren, geben Sie Ihren Endpunkt, die Authentifizierungsmethode und die Retry-Richtlinie an. Die Konfiguration erfolgt durch das Unico-Team — kontaktieren Sie Ihr CS / Onboarding-Team, um einen Webhook zu registrieren oder zu aktualisieren.

Erforderliche Informationen

Feld	Beschreibung
Benachrichtigungs-URL	Endpunkt, den Unico aufruft, um Ereignisbenachrichtigungen zu liefern. Muss über HTTPS erreichbar sein.
Authentifizierungstyp	Wie Unico sich gegenüber Ihrem Endpunkt authentifiziert. Siehe Optionen unten.
Retry-Einstellungen	Maximale Anzahl von Versuchen und Intervall zwischen Versuchen (exponentielles Backoff wird angewendet).
Parallelitätslimit	Maximale Anzahl gleichzeitiger aktiver Lieferungen (max: 500).
Timeout	Maximale Wartezeit für die Antwort des Endpunkts, in Sekunden.
Zu benachrichtigende Status	Die Menge der Prozesszustände, die eine Benachrichtigung auslösen. Derzeit fest auf PROCESS_STATE_FINISHED gesetzt; zu diesem Zeitpunkt nicht konfigurierbar.

Authentifizierungsmethoden

OAuth2

Angabe erforderlich:

• Webhook-endpoint
• OAuth2-Provider-URL
• OAuth2-Provider-ClientId
• OAuth2-Provider-Secret

Unico fordert ein Zugriffstoken vom Provider-URL mithilfe der Client-Anmeldeinformationen an und leitet es als Bearer-Token an Ihren Endpunkt weiter.

Basic Authorization

Geben Sie Anmeldeinformationen im Format user:pass an. Unico kodiert diese in Base64 und sendet sie im Authorization: Basic <encoded>-Header bei jedem Webhook-Aufruf.

API Key

Zwei Formate werden unterstützt. Die Zeichenkette wird am ersten Doppelpunkt aufgeteilt:

• header:value — legt einen benutzerdefinierten Header-Namen fest. Beispiele:
  • X-API-Key:abc123 → X-API-Key: abc123
  • Authorization:Bearer abc123 → Authorization: Bearer abc123
• Nur value (kein Doppelpunkt) — der Wert wird als Authorization-Header ohne Schema-Präfix gesendet. Beispiel: abc123 → Authorization: abc123.

Verwenden Sie das Format header:value, wenn Sie ein Bearer-Schema benötigen (z. B. Authorization:Bearer <token>); das Nur-Wert-Format sendet den reinen Wert ohne Präfix.

Keine Authentifizierung

Es werden keine Anmeldeinformationen gesendet. Nur für Entwicklungsumgebungen empfohlen — Produktionsendpunkte sollten stets eine Authentifizierung erfordern.

Prozesszustände, die Benachrichtigungen auslösen

Derzeit sendet Unico eine Benachrichtigung, wenn ein Prozess in folgenden Zustand wechselt:

Zustand	Beschreibung
PROCESS_STATE_FINISHED	Prozess abgeschlossen — terminaler Zustand, unabhängig vom Ergebnis.

Zustände können sich weiterentwickeln

Die Menge der von der Plattform benachrichtigten Zustände kann sich in Zukunft ändern. Machen Sie die Zustände, auf die Ihr Endpunkt reagiert, konfigurierbar, damit das Hinzufügen eines neuen Zustands keine erneute Bereitstellung Ihres Dienstes erfordert.

Anforderungsformat

Webhook-Lieferungen sind POST-Anfragen an Ihren Endpunkt. Der Body enthält den Prozessidentifikator und den aktuellen Zustand. Alle Felder sind obligatorisch.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

Für das vollständige Payload-Schema und die Liste der lastEvent-Werte, siehe Ereignistypen.

Erwartete Antwort

Ihr Endpunkt muss synchron antworten:

• Erfolg: Jeder HTTP-Status im 200–299-Bereich.
• Fehler: Jeder andere Status. Unico wiederholt den Versuch mit exponentiellem Backoff bis zur konfigurierten maximalen Anzahl von Versuchen oder bis ein 2xx empfangen wird.

Schnell antworten

Bestätigen Sie den Webhook schnell (innerhalb Ihres konfigurierten Timeouts) und verarbeiten Sie den Payload asynchron auf Ihrer Seite. Langwierige Verarbeitung innerhalb des Webhook-Handlers erhöht die Wahrscheinlichkeit von Timeouts und unnötigen Retries.

Für Hinweise zu Idempotenz und Retry-Behandlung, siehe Sicherheit.