--- title: Webhook description: Legen Sie fest, wo IDCloud Ihr System benachrichtigt, wenn sich der Status einer Journey ändert, wie es sich gegenüber Ihrer API authentifiziert und was passiert, wenn Ihre API nicht antwortet. canonical: https://developer.unico.io/de/dual-api/product-guide/portal-idcloud/settings/webhook locale: de generated_by: markdown-export --- **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. :::info **Für wen es gedacht ist:** Kunden, die Journey-Ergebnisse automatisch erhalten möchten, ohne Polling. Gilt für alle Integrationstypen. **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 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 zur Verwaltung Ihres Webhooks, mit der Schaltfläche Webhook konfigurieren](/img/product-guide/webhook/en/01-manage-webhook.png) *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](/img/product-guide/webhook/en/02-edit-webhook.png) *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 zugehörigen Felder für Zugangsdaten](/img/product-guide/webhook/en/02-edit-webhook.png) *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](/img/product-guide/webhook/en/02-edit-webhook.png) *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 ```text 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 ```