Webhook

Webhook ist die Art und Weise, wie IDCloud Ihrem System automatisch mitteilt, wenn in einer Identitätsprüfungs-Journey etwas passiert. Anstatt dass Ihr System fragt „Ist es schon fertig?“, ruft IDCloud Ihre API in dem Moment auf, in dem das Ereignis eintritt.

Auf diesem Bildschirm legen Sie die Adresse Ihrer API fest, wie IDCloud sich dagegen authentifiziert und was passiert, wenn sie nicht antwortet.

Information

Für wen es gedacht ist: Kunden, die Journey-Ergebnisse automatisch erhalten möchten, ohne Polling. Gilt sowohl für byUnico- als auch für byClient-Integrationen.

Was sich in Ihrem System ändert: Es erhält nun bei jeder Statusänderung eine Benachrichtigung, anstatt IDCloud abfragen zu müssen.

Wo Sie es finden: IDCloud Portal → Seitenleiste Einstellungen → Tab Webhook.

Bevor es diesen Bildschirm gab, erforderte jede Webhook-Änderung ein Support-Ticket — allein dafür etwa 30 Tickets pro Monat. Jetzt erledigen Sie es selbst, innerhalb von Minuten, sowohl in Staging als auch in Production.

Bevor Sie beginnen

Zugriffsberechtigung

Ihr Benutzer benötigt das Profil Configurator — dasselbe, das Zugriff auf die Journey Customization gewährt. Wenn der Tab Webhook nicht angezeigt wird, wenden Sie sich an Ihren Account-Administrator.

Wie die Konfiguration angewendet wird

Umfang	Ein Webhook pro Mandant und Branch. Es gibt keine Liste: Wenn bereits einer konfiguriert ist, wird er bearbeitet, nicht dupliziert.
Getrennte Umgebungen	Das Staging-Portal konfiguriert den UAT-Webhook; das Production-Portal konfiguriert Production. Die Konfiguration des einen wirkt sich nicht auf den anderen aus.
Wann es wirksam wird	Sobald Sie speichern.
Sicherheit des Secrets	Das Secret wird verschlüsselt und nie wieder im Klartext angezeigt. Auf dem Bildschirm ist es immer maskiert.

Was Sie bereithalten sollten

• Die HTTPS-URL Ihrer API, die die Benachrichtigungen empfängt. Sie muss vor dem Speichern live sein und Anfragen entgegennehmen.
• Die Zugangsdaten, die Ihre API erwartet, abhängig von der gewählten Authentifizierungsmethode (siehe Schritt 3).
• Falls Ihre API ein Kapazitätslimit hat, die Anzahl der Anfragen pro Sekunde, die sie unterstützt.

Was Sie vorher entscheiden sollten

Zwei technische Entscheidungen hängen von der Person ab, die Ihre API betreut, nicht von der Person, die das Portal bedient. Es lohnt sich, dies vor dem Öffnen des Bildschirms abzustimmen:

• Welche Authentifizierungsmethode Ihre API erfordert.
• Ob Sie die Retries anpassen oder bei den Standardwerten bleiben. Der Standard funktioniert für die meisten Fälle.

Schritt für Schritt

Schritt 1 — Öffnen Sie den Tab Webhook

Klicken Sie im IDCloud Portal in der Seitenleiste auf das Zahnrad-Symbol (Einstellungen) und wählen Sie den Tab Webhook.

Wenn noch kein Webhook konfiguriert ist, zeigt der Bildschirm „Keine Webhooks erstellt“ und eine Schaltfläche Webhook erstellen. Wenn bereits einer existiert, zeigt der Bildschirm die Karte Ihr Webhook mit dem Endpoint, dem Authentifizierungstyp und dem maskierten Secret, sowie eine Schaltfläche Webhook konfigurieren, um ihn zu bearbeiten.

Karte „Ihr Webhook“ mit Endpoint, Authentifizierungstyp und maskiertem Secret.

Schritt 2 — Geben Sie die URL Ihrer API ein

Klicken Sie auf Webhook erstellen (oder Webhook konfigurieren, falls bereits einer existiert) und füllen Sie das Feld Client-URL (Endpoint) unter „Client-Informationen“ aus.

Dies ist die Adresse, an die IDCloud Benachrichtigungen sendet. Sie muss HTTPS sein.

Richten Sie sie auf eine Adresse, die bereits live ist. IDCloud beginnt, diese URL aufzurufen, sobald Sie speichern. Wenn sie noch nicht existiert, schlagen die ersten Benachrichtigungen fehl und verbrauchen die Retries, bevor Ihr Team es bemerkt.

Feld Endpoint mit dem Hilfetext zur HTTPS-Anforderung.

Schritt 3 — Wählen Sie, wie sich IDCloud gegenüber Ihrer API authentifiziert

Wählen Sie unter „Authentifizierung“ den Authentifizierungstyp. Es gibt vier Optionen, und jede fragt nach unterschiedlichen Feldern:

Typ	Angezeigte Felder	Wann verwenden
None	keine	Ihre API erfordert keine Authentifizierung. Verwenden Sie dies nur, wenn ein anderer Schutz besteht — ohne Authentifizierung kann jeder, der die URL entdeckt, Daten dorthin senden
API Key	Secret	Ihre API validiert einen festen Schlüssel
Basic Auth	Secret	Ihre API verwendet Benutzername und Passwort im HTTP-Basic-Stil
OAuth 2.0	Auth-URL, Client-ID, Secret	Ihre API erfordert ein Token. IDCloud ruft das Token von dieser URL ab und erneuert es eigenständig

Bei OAuth 2.0 ist die Auth-URL die Adresse, von der IDCloud das Token abruft — sie ist nicht die URL, die die Benachrichtigungen empfängt. Es handelt sich um unterschiedliche Adressen, und sie zu vertauschen ist der häufigste Fehler auf diesem Bildschirm.

Das Secret wird verschlüsselt gespeichert. Beim Bearbeiten eines bestehenden Webhooks wird das Feld leer angezeigt: Wird es ausgefüllt, überschreibt dies das aktuelle Secret; bleibt es leer, wird das vorhandene beibehalten.

Stimmen Sie die Methode vor dem Speichern mit der Person ab, die Ihre API betreut. Die falsche Authentifizierung erzeugt keinen Fehler auf dem Bildschirm — sie erzeugt eine Benachrichtigung, die anschließend lautlos fehlschlägt, und Sie merken es erst, wenn ein Ergebnis nicht ankommt.

Feld Authentifizierungstyp und die entsprechenden Felder für Zugangsdaten.

Schritt 4 — Passen Sie bei Bedarf die Retries an

Der Abschnitt Retry-Konfiguration ist optional und standardmäßig deaktiviert. Aktivieren Sie ihn nur, wenn Sie das Standardverhalten ändern müssen.

Beim Aktivieren werden sechs Felder angezeigt:

Feld	Was es steuert	Standard
Maximale Retries	Wie oft IDCloud es erneut versucht, bevor es aufgibt	—
Rate Limit (Anfragen/s)	Maximale Benachrichtigungen pro Sekunde. Senken Sie diesen Wert, wenn Ihre API eine begrenzte Kapazität hat	—
Minimale Zeit (s)	Minimales Intervall zwischen den Versuchen	2s
Maximale Zeit (s)	Maximales Intervall zwischen den Versuchen	10s
Maximale Dauer (s)	Wie lange pro Versuch gewartet wird, bevor er als Fehlschlag gilt	2s
Maximale Verdopplungen	Wachstumsfaktor des Intervalls zwischen den Versuchen (Backoff)	5

Das kombinierte Verhalten: IDCloud versucht es, wartet die minimale Zeit, versucht es erneut und erhöht das Intervall gemäß den maximalen Verdopplungen bis zur maximalen Zeit — dies wird wiederholt, bis die maximalen Retries erreicht sind. Jeder einzelne Versuch gibt nach der maximalen Dauer auf.

Passen Sie das Rate Limit an, bevor Sie etwas anderes ändern. Wenn Ihre API unter Last zusammenbricht, liegt das Problem am Durchsatz, nicht an den Retries — und mehr Retries in diesem Szenario verschlimmern es, da sie die Aufrufe vervielfachen. Senken Sie zuerst die Rate.

Mehr maximale Retries ersetzen keine stabile API. Retries decken vorübergehende Nichtverfügbarkeit ab. Wenn Ihre API häufig fehlschlägt, verzögert diese Einstellung nur den Zeitpunkt, an dem Sie die Benachrichtigung verlieren.

Die sechs Retry-Felder, angezeigt nach dem Aktivieren des Schalters.

Schritt 5 — Speichern

Klicken Sie auf Speichern. Abbrechen verwirft alles und behält die vorherige Konfiguration bei.

IDCloud validiert die Token-URL, bevor das Speichern zugelassen wird, wenn die Methode OAuth 2.0 ist.

Nach dem Speichern zeigt die Karte Ihr Webhook den Endpoint und den Authentifizierungstyp an. Das Secret wird maskiert angezeigt und kann nicht mehr über den Bildschirm abgerufen werden — wenn Sie den Wert verlieren, müssen Sie einen neuen festlegen.

Führen Sie einen echten Test durch, bevor Sie es als abgeschlossen betrachten. Starten Sie eine Journey in Staging und bestätigen Sie, dass die Benachrichtigung Ihre API erreicht hat. Der Bildschirm bestätigt, dass die Konfiguration gespeichert wurde, nicht dass Ihre API sie erhalten hat.

FAQ

Kann ich mehr als einen Webhook registrieren? Nein. Es gibt einen Webhook pro Mandant und Branch. Wenn bereits einer existiert, wird er bearbeitet — es gibt keine Möglichkeit, einen zweiten zu erstellen.

Ich habe ihn in Staging konfiguriert. Gilt das auch für Production? Nein. Die Umgebungen sind unabhängig: Das Staging-Portal konfiguriert den UAT-Webhook, und das Production-Portal konfiguriert Production. Sie müssen die Konfiguration im Production-Portal wiederholen.

Wie sehe ich das registrierte Secret? Das können Sie nicht. Es wird beim Speichern verschlüsselt und immer maskiert angezeigt. Wenn Sie den Wert verloren haben, registrieren Sie über das Feld Secret ein neues — das Ausfüllen überschreibt das vorherige.

Ich habe den Webhook bearbeitet, möchte aber das Secret nicht ändern. Was mache ich? Lassen Sie das Feld Secret leer. Der aktuelle Wert wird beibehalten.

Wie lösche ich einen Webhook? Der Bildschirm bietet keine Löschfunktion an. Um die Konfiguration zu entfernen, wenden Sie sich an den Unico-Support. Wenn das Ziel lediglich ist, keine Benachrichtigungen mehr zu erhalten oder das Ziel zu ändern, bearbeiten Sie stattdessen die URL.

Ich habe gespeichert, und die Benachrichtigungen kommen nicht an. Prüfen Sie in dieser Reihenfolge: ob die URL korrekt und HTTPS ist; ob Ihre API live ist; ob die Authentifizierungsmethode der erwarteten entspricht; und ob das Secret korrekt eingegeben wurde. Authentifizierungsfehler werden auf diesem Bildschirm nicht als Fehler angezeigt — sie treten zum Zeitpunkt der Zustellung auf.

Was ist der Unterschied zwischen „Maximale Dauer“ und „Maximale Zeit“? „Maximale Zeit“ ist das längste Intervall zwischen zwei Versuchen. „Maximale Dauer“ ist, wie lange IDCloud pro Versuch wartet, bevor er als Fehlschlag gilt.

Brauche ich einen Webhook, wenn ich das Ergebnis bereits über die API abfrage (Polling)? Es ist nicht erforderlich, erspart Ihrem System jedoch das Polling. Wenn Sie bereits eine funktionierende Polling-Routine haben, ist der Webhook eine Optimierung, keine Notwendigkeit.

Kurzreferenz

IDCloud Portal
 └─ Einstellungen (Zahnrad-Symbol in der Seitenleiste)
     └─ Tab Webhook
         ├─ Client-Informationen ....... Client-URL (Endpoint), HTTPS
         ├─ Authentifizierung .......... None | API Key | Basic Auth | OAuth 2.0
         │                             OAuth 2.0: + Auth-URL und Client-ID
         └─ Retries (optional) ........ Maximale Retries
                                       Rate Limit (Anfragen/s)
                                       Minimale Zeit (2s) · Maximale Zeit (10s)
                                       Maximale Dauer (2s) · Maximale Verdopplungen (5)

Ein Webhook pro Mandant und Branch · UAT und Production unabhängig · Secret nie angezeigt · Abbrechen · Speichern