---
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/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.

> **Information:** **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 fünf 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 |
| **mTLS** | Client-Zertifikat, Privater Schlüssel, Server-CA (optional) | Ihre API akzeptiert nur Aufrufe von Clients, die ein Zertifikat vorlegen (Mutual TLS). IDCloud legt bei jeder Benachrichtigung das Zertifikat vor, das Sie angeben |

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.*

#### mTLS einrichten

Bei **mTLS** identifiziert sich IDCloud gegenüber Ihrer API, indem es ein Client-Zertifikat vorlegt
(Mutual TLS), anstatt einen Schlüssel, ein Passwort oder ein Token zu senden. Ihre API muss so
eingerichtet sein, dass sie dieses Zertifikat anfordert und der Stelle vertraut, die es ausgestellt
hat. Wenn Sie **mTLS** auswählen, werden drei Felder angezeigt:

| Feld | Was Sie angeben müssen |
| :- | :- |
| **Client-Zertifikat (PEM)** | Die Zertifikatskette im PEM-Format, Leaf-Zertifikat zuerst. Fügen Sie die Zwischenzertifikate nach Ihrem eigenen Zertifikat hinzu, damit Ihre API das Zertifikat mit einer Zertifizierungsstelle verknüpfen kann, der sie vertraut |
| **Privater Schlüssel (PEM)** | Der Schlüssel, der zum Zertifikat gehört, im PEM-Format und **ohne Passwort**. Er wird verschlüsselt gespeichert und nie wieder angezeigt |
| **Server-CA (PEM, optional)** | Nur wenn das eigene Zertifikat Ihrer API von einer privaten Zertifizierungsstelle signiert ist. Ohne diese Angabe vertraut IDCloud öffentlichen Zertifizierungsstellen |

Sie können eine `.pem`-Datei auswählen oder den Text einfügen. Jedes Feld kann bis zu
20.000 Zeichen enthalten.

Einige Regeln, die Sie kennen sollten, bevor Sie sich für mTLS entscheiden:

- **Die URL muss HTTPS sein**, und Ihre API muss TLS 1.2 oder neuer akzeptieren.
- **Nach dem Speichern ist der Typ gesperrt.** Der Authentifizierungstyp kann auf diesem Bildschirm
  nicht auf einen anderen geändert werden. Um die Methode zu wechseln, wenden Sie sich an den
  Unico-Support.
- **Es werden keine weiteren Zugangsdaten gesendet.** mTLS kann im selben Webhook nicht mit
  API Key, Basic Auth oder OAuth 2.0 kombiniert werden.
- **Weiterleitungen gelten als Fehlschläge.** IDCloud folgt ihnen nicht. Richten Sie die URL daher
  auf die endgültige Adresse.

### 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. Bei mTLS validiert IDCloud stattdessen das Zertifikat und den Schlüssel: Beide müssen im
PEM-Format vorliegen, der Schlüssel darf kein Passwort haben und muss zum Zertifikat passen, und
das Zertifikat muss innerhalb seines Gültigkeitszeitraums liegen.

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 ersetze ich das mTLS-Zertifikat, bevor es abläuft?** Bearbeiten Sie den Webhook. Das
Zertifikat und der private Schlüssel werden maskiert angezeigt. Geben Sie das neue Zertifikat
**und** den neuen privaten Schlüssel an — beides ist erforderlich, auch wenn sich nur eines davon
geändert hat — sowie erneut die Server-CA, falls Sie eine verwenden. Speichern Sie anschließend.
IDCloud beginnt innerhalb von etwa 5 Minuten, das neue Zertifikat zu verwenden. Halten Sie das
vorherige daher etwas länger als diese Zeitspanne gültig, bevor Sie es widerrufen. Wenn Sie die
drei Felder unverändert lassen, wird weiterhin das aktuelle Zertifikat verwendet.

**Kann ich von mTLS zu einem anderen Authentifizierungstyp wechseln?** Nicht auf diesem Bildschirm:
Nach dem Speichern ist der Typ gesperrt. Wenden Sie sich an den Unico-Support, um die
Webhook-Konfiguration zu entfernen, und erstellen Sie sie anschließend mit der neuen Methode
erneut.

**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.
Bei mTLS prüfen Sie außerdem, ob Ihre API der Stelle vertraut, die das Zertifikat ausgestellt hat,
ob das Zertifikat nicht abgelaufen ist und ob die Server-CA ausgefüllt ist, wenn das Zertifikat
Ihrer API von einer privaten Zertifizierungsstelle stammt. 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 | mTLS
         │                             OAuth 2.0: + Auth-URL und Client-ID
         │                             mTLS: + Client-Zertifikat, Privater Schlüssel, Server-CA (optional)
         └─ 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
```