Webhook
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.
Who it's for: customers who want to receive journey results automatically, without polling. Applies to both byUnico and byClient integrations.
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 this screen existed, any webhook change required a support ticket — around 30 tickets a month just for that. Now you do it yourself, in minutes, in both Staging and Production.
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.
"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 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 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.
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
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