--- title: Einrichtung description: Schritt-für-Schritt-Anleitung zur Konfiguration von IDCloud Webhooks — Self-Service über das Portal für Web- und SDK-Integrationen sowie clientbasierte Konfiguration für API-Integrationen mit Check-Orchestrierung (nur Brasilien). canonical: https://developer.unico.io/de/dual-api/developers/webhooks-and-events/setup locale: de generated_by: markdown-export --- IDCloud unterstützt zwei Webhook-Modalitäten, abhängig von Ihrer Integrationsart: - **Via Portal** — für Web- und SDK-Integrationen. Self-Service-Konfiguration direkt im IDCloud-Portal. - **By client** — für API-Integrationen, die die **Check-Orchestrierung** nutzen (ein asynchroner Flow). Konfiguration durch das Unico-Team. Nur in **Brasilien** verfügbar. ### Via Portal (Web & SDK) Um Ihren Webhook-Endpunkt zu registrieren oder zu aktualisieren, öffnen Sie das IDCloud-Portal und navigieren Sie zu **Einstellungen > Webhook**. #### 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 `-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 `); 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. | :::warning[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. ```json { "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0", "state": "PROCESS_STATE_FINISHED", "flow": "id" } ``` :::note[`lastEvent` und `lastEventDescription`] Diese beiden Felder erscheinen im Payload **nur, wenn der Prozess abgelaufen ist**, bevor der Benutzer die Journey abgeschlossen hat. Sie fehlen in normalen Abschluss-Payloads. Das vollständige Schema und die Liste der möglichen `lastEvent`-Werte finden Sie unter [Ereignistypen](/developers/webhooks-and-events/event-types). ::: #### 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. :::tip[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](/developers/webhooks-and-events/security). ### By client (API — nur Brasilien) :::info[Nur Brasilien] Der clientbasierte Webhook ist ausschließlich für API-Integrationen in Brasilien verfügbar, die die **Check-Orchestrierung** nutzen — ein asynchroner Flow, bei dem das Prozessergebnis per Webhook geliefert wird anstatt als synchrone API-Antwort. ::: Um Ihren Endpunkt zu registrieren oder zu aktualisieren, kontaktieren Sie Ihr **CS / Onboarding**-Team. #### Erforderliche Informationen | Feld | Beschreibung | |---|---| | **Benachrichtigungs-URL** | Endpunkt, den Ihr System bereitstellt, um Statusaktualisierungen zu empfangen. 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. | #### 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 `-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 `); 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. #### Statuscodes Der clientbasierte Webhook verwendet **numerische Statuscodes**: | Code | Beschreibung | |---|---| | `2` | Abweichung — der Prozess wurde mit einer Abweichung bei der Identitätsprüfung abgeschlossen. | | `3` | Abgeschlossen — der Prozess wurde erfolgreich abgeschlossen. | | `5` | Fehler — der Prozess wurde aufgrund eines Fehlers beendet. | #### Anforderungsformat Webhook-Lieferungen sind **POST**-Anfragen an Ihren Endpunkt. Der Body enthält den Transaktionsidentifikator und den numerischen Statuscode. ```json { "id": "8263a268-5388-492a-bca2-28e1ff4a69f0", "status": 3 } ``` #### 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. :::tip[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. ::: :::warning[Mindestens-einmal-Lieferung] Die Plattform garantiert Mindestens-einmal-Lieferung — dieselbe Benachrichtigung kann mehr als einmal ankommen. Implementieren Sie auf Ihrer Seite Idempotenz mithilfe des `id`-Felds, um Duplikate sicher zu behandeln. Für Hinweise zu Idempotenz und Retry-Behandlung, siehe [Sicherheit](/developers/webhooks-and-events/security). :::