---
title: Webhook
description: Configure where IDCloud notifies your system when a journey changes state, how it authenticates against your API, and what happens when your API doesn't respond.
canonical: https://developer.unico.io/dual-api/product-guide/portal-idcloud/settings/webhook
locale: en
generated_by: markdown-export
---

**Webhook** is how IDCloud automatically tells your system when something happens in an identity
verification journey. Instead of your system asking "is it done yet?", IDCloud calls your API the
moment the event occurs.

On this screen you set your API's address, how IDCloud authenticates against it, and what happens
when it doesn't respond.

:::info
**Who it's for:** customers who want to receive journey results automatically, without polling.
Applies to all integration types.

**What changes in your system:** it now receives a notification on every state change, instead of
needing to poll IDCloud.

**Where to find it:** IDCloud Portal → sidebar **Settings** → **Webhook** tab.
:::

## Before you start

### Access permission

Your user needs the **Configurator** profile — the same one that grants access to Journey
Customization. If the Webhook tab doesn't show up, talk to your account administrator.

### How the configuration is applied

| | |
| :- | :- |
| **Scope** | One webhook per **tenant and branch**. There's no list: if one is already configured, it gets edited, not duplicated. |
| **Separate environments** | The Staging Portal configures the UAT webhook; the Production one configures Production. Configuring one doesn't affect the other. |
| **When it takes effect** | As soon as you save. |
| **Secret security** | The secret is encrypted and never shown again in plain text. On screen it's always masked. |

### What to have ready

- The **HTTPS URL** of your API that will receive the notifications. It needs to be live and
  accepting requests before you save.
- The **credentials** your API expects, based on the authentication method you choose (see
  Step 3).
- If your API has a capacity limit, the number of **requests per second** it supports.

### What to decide beforehand

Two technical decisions depend on whoever maintains your API, not on whoever operates the Portal.
Worth aligning before opening the screen:

- **Which authentication method** your API requires.
- **Whether you'll adjust the retries** or leave them at the default. The default works for most
  cases.

## Step by step

### Step 1 — Open the Webhook tab

In the IDCloud Portal, click the **gear icon (Settings)** in the sidebar and select the
**Webhook** tab.

If you don't have a webhook configured yet, the screen shows **"No webhooks created"** and a
**Create webhook** button. If you already have one, the screen shows the **Your webhook** card
with the endpoint, authentication type, and masked secret, plus a **Configure webhook** button to
edit it.

![Manage your webhook card, with the Configure webhook button](/img/product-guide/webhook/en/01-manage-webhook.png)

*"Your webhook" card with endpoint, authentication type, and masked secret.*

### Step 2 — Enter your API's URL

Click **Create webhook** (or **Configure webhook**, if one already exists) and fill in the
**Client URL (Endpoint)** field, under "Client information".

This is the address IDCloud will send notifications to. It needs to be **HTTPS**.

**Point it at an address that's already live.** IDCloud starts calling this URL as soon as you
save. If it doesn't exist yet, the first notifications will fail and burn through the retries
before your team notices.

![Endpoint field, with the HTTPS requirement helper text](/img/product-guide/webhook/en/02-edit-webhook.png)

*Endpoint field, with the helper text about the HTTPS requirement.*

### Step 3 — Choose how IDCloud authenticates against your API

Under "Authentication", select the **Authentication type**. There are four options, and each
asks for different fields:

| Type | Fields shown | When to use |
| :- | :- | :- |
| **None** | none | Your API doesn't require authentication. Only use this if it has some other protection — with no authentication, anyone who discovers the URL can send data to it |
| **API Key** | Secret | Your API validates a fixed key |
| **Basic Auth** | Secret | Your API uses username and password, HTTP Basic style |
| **OAuth 2.0** | Auth URL, Client ID, Secret | Your API requires a token. IDCloud fetches the token from that URL and renews it on its own |

For **OAuth 2.0**, the **Auth URL** is the address where IDCloud fetches the token — it's not the
URL that receives the notifications. They're different addresses, and swapping them is the most
common mistake on this screen.

The **Secret** is stored encrypted. When editing an existing webhook, the field shows up empty:
filling it in overwrites the current secret, and leaving it blank keeps what's already there.

**Confirm the method with whoever maintains your API before saving.** The wrong authentication
doesn't produce an error on screen — it produces a notification that fails silently afterward,
and you only find out when a result doesn't arrive.

![Authentication type field and the matching credential fields](/img/product-guide/webhook/en/02-edit-webhook.png)

*Authentication type field and the corresponding credential fields.*

### Step 4 — Adjust the retries, if needed

The **Retry configuration** section is **optional** and starts off. Only turn it on if you need
to change the default behavior.

Turning it on reveals six fields:

| Field | What it controls | Default |
| :- | :- | :- |
| **Maximum retries** | How many times IDCloud tries again before giving up | — |
| **Rate limit (req/s)** | Maximum notifications per second. Lower it if your API has limited capacity | — |
| **Minimum time (s)** | Minimum interval between attempts | 2s |
| **Maximum time (s)** | Maximum interval between attempts | 10s |
| **Maximum duration (s)** | How long to wait per attempt before considering it a failure | 2s |
| **Maximum doublings** | Growth factor of the interval between attempts (backoff) | 5 |

The combined behavior: IDCloud tries, waits the **minimum time**, tries again, and keeps
increasing the interval according to **maximum doublings** up to the **maximum time** — repeating
until **maximum retries**. Each individual attempt gives up after the **maximum duration**.

**Adjust the Rate limit before touching anything else.** If your API falls over under load, the
problem is throughput, not retries — and increasing retries in that scenario makes it worse,
since it multiplies the calls. Lower the rate first.

**Increasing Maximum retries doesn't replace a stable API.** Retries cover momentary
unavailability. If your API fails frequently, this setting only delays the moment you lose the
notification.

![The six retry fields, shown after turning on the toggle](/img/product-guide/webhook/en/02-edit-webhook.png)

*The six retry fields, shown after turning on the toggle.*

### Step 5 — Save

Click **Save**. **Cancel** discards everything and keeps the previous configuration.

IDCloud validates the token URL before allowing you to save, when the method is OAuth 2.0.

After saving, the **Your webhook** card shows the endpoint and authentication type. The secret
shows up masked and can no longer be retrieved from the screen — if you lose the value, you'll
need to set a new one.

**Run a real test before considering it done.** Start a journey in Staging and confirm the
notification reached your API. The screen confirms the configuration was saved, not that your API
received it.

## FAQ

**Can I register more than one webhook?** No. It's one webhook per tenant and branch. If one
already exists, it gets edited — there's no way to create a second one.

**I configured it in Staging. Does it apply to Production too?** No. The environments are
independent: the Staging Portal configures the UAT webhook, and the Production one configures
Production. You need to repeat the configuration in the Production Portal.

**How do I see the secret I registered?** You can't. It's encrypted on save and always shown
masked. If you lost the value, register a new one via the Secret field — filling it in overwrites
the previous one.

**I edited the webhook but don't want to change the secret. What do I do?** Leave the Secret
field blank. The current value is kept.

**How do I delete a webhook?** The screen doesn't offer deletion. To remove the configuration,
contact Unico support. If the goal is just to stop receiving notifications or change the
destination, edit the URL instead.

**I saved and the notifications aren't arriving.** Check, in this order: the URL is correct and
is HTTPS; your API is live; the authentication method is what it expects; and the secret was
typed correctly. Authentication failures don't show up as an error on this screen — they happen
at delivery time.

**What's the difference between "Maximum duration" and "Maximum time"?** "Maximum time" is the
longest interval **between** two attempts. "Maximum duration" is how long IDCloud waits **per**
attempt before considering it a failure.

**Do I need a webhook if I already poll for the result via the API?** It's not required, but it
saves your system from having to poll. If you already have a working polling routine, the webhook
is an optimization, not a requirement.

## Quick reference

```text
IDCloud Portal
 └─ Settings (gear icon in the sidebar)
     └─ Webhook tab
         ├─ Client information ....... Client URL (Endpoint), HTTPS
         ├─ Authentication ............ None | API Key | Basic Auth | OAuth 2.0
         │                             OAuth 2.0: + Auth URL and Client ID
         └─ Retries (optional) ....... Maximum retries
                                       Rate limit (req/s)
                                       Minimum time (2s) · Maximum time (10s)
                                       Maximum duration (2s) · Maximum doublings (5)

One webhook per tenant and branch · UAT and Production independent · Secret never shown · Cancel · Save
```