Zum Hauptinhalt springen

Einrichtung

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.

Um Ihren Webhook-Endpunkt zu registrieren oder zu aktualisieren, öffnen Sie das IDCloud-Portal und navigieren Sie zu Einstellungen > Webhook.

Erforderliche Informationen​

FeldBeschreibung
Benachrichtigungs-URLEndpunkt, den Unico aufruft, um Ereignisbenachrichtigungen zu liefern. Muss über HTTPS erreichbar sein.
AuthentifizierungstypWie Unico sich gegenüber Ihrem Endpunkt authentifiziert. Siehe Optionen unten.
Retry-EinstellungenMaximale Anzahl von Versuchen und Intervall zwischen Versuchen (exponentielles Backoff wird angewendet).
ParallelitätslimitMaximale Anzahl gleichzeitiger aktiver Lieferungen (max: 500).
TimeoutMaximale Wartezeit für die Antwort des Endpunkts, in Sekunden.
Zu benachrichtigende StatusDie 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:

ZustandBeschreibung
PROCESS_STATE_FINISHEDProzess 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.

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

Diese beiden Felder erscheinen im Payload nur wenn result = expired — d. h. 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.

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.

Zuletzt aktualisiert am