---
title: Setup
description: Step-by-step guide to configuring IDCloud webhooks — portal self-service for Web and SDK, and by-client configuration for API integrations using Check orchestration (Brazil only).
canonical: https://developer.unico.io/dual-api/developers/webhooks-and-events/setup
locale: en
generated_by: markdown-export
---

IDCloud supports two webhook modalities, depending on how you integrate:

- **Via Portal** — for Web and SDK integrations. Self-service configuration directly in the IDCloud portal.
- **By client** — for API integrations using the **Check orchestration** capability (an asynchronous flow). Configured by the Unico team. Available in **Brazil only**.

### Via Portal (Web & SDK)

To register or update your webhook endpoint, access the IDCloud portal and navigate to **Settings > Webhook**.

#### Required information

| Field | Description |
|---|---|
| **Notification URL** | Endpoint Unico will call to deliver event notifications. Must be reachable via HTTPS. |
| **Authentication type** | How Unico authenticates against your endpoint. See options below. |
| **Retry settings** | Maximum number of attempts and interval between attempts (exponential backoff is applied). |
| **Concurrency limit** | Maximum number of simultaneous in-flight deliveries (max: **500**). |
| **Timeout** | Maximum wait time for the endpoint's response, in seconds. |
| **Status to notify** | The set of process states that trigger a notification. Currently fixed to `PROCESS_STATE_FINISHED`; not configurable at this time. |

#### Authentication methods

****OAuth2****

Provide:

  - Webhook `endpoint`
  - OAuth2 provider `URL`
  - OAuth2 provider `ClientId`
  - OAuth2 provider `Secret`

  Unico will request an access token from the provider URL using the client credentials and forward it to your endpoint as a Bearer token.

****Basic Authorization****

Provide credentials in the format `user:pass`. Unico encodes them in Base64 and sends them in the `Authorization: Basic <encoded>` header on every webhook call.

****API Key****

Two formats are supported. The string is split on the **first** colon:

  - `header:value` — sets a custom header name. Examples:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` only (no colon) — the value is sent as the `Authorization` header with no scheme prefix. Example: `abc123` → `Authorization: abc123`.

  Use the `header:value` format when you need a Bearer scheme (e.g., `Authorization:Bearer <token>`); the value-only format sends the raw value without a prefix.

****No authentication****

No credentials are sent. Only recommended for development environments — production endpoints should always require authentication.

#### Process states that trigger notifications

Currently, Unico sends a notification whenever a process transitions to:

| State | Description |
|---|---|
| `PROCESS_STATE_FINISHED` | Process finished — terminal state, regardless of outcome. |

:::warning[States may evolve]
The set of states notified by the platform may change in the future. Make the states your endpoint reacts to **configurable**, so adding a new state does not require redeploying your service.
:::

#### Request format

Webhook deliveries are **POST** requests to your endpoint. The body contains the process identifier and current state.

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`lastEvent` and `lastEventDescription`]
These two fields appear in the payload **only when the process expired** before the user completed the journey. They are absent from normal completion payloads. See [Event types](/developers/webhooks-and-events/event-types) for the full schema and the list of possible `lastEvent` values.
:::

#### Expected response

Your endpoint must respond **synchronously**:

- **Success**: any HTTP status in the `200`–`299` range.
- **Failure**: any other status. Unico will retry with exponential backoff up to the configured maximum number of attempts, or until a `2xx` is received.

:::tip[Respond fast]
Acknowledge the webhook quickly (under your configured timeout) and process the payload asynchronously on your side. Long-running processing inside the webhook handler increases the chance of timeouts and unnecessary retries.
:::

For idempotency and retry handling guidance, see [Security](/developers/webhooks-and-events/security).

### By client (API — Brazil only)

:::info[Brazil only]
The by-client webhook is available exclusively for API integrations in Brazil that use the **Check orchestration** capability — an asynchronous flow where the process result is delivered via webhook rather than as a synchronous API response.
:::

To register or update your endpoint, contact your **CS / Onboarding** team.

#### Required information

| Field | Description |
|---|---|
| **Notification URL** | Endpoint your system exposes to receive status updates. Must be reachable via HTTPS. |
| **Authentication type** | How Unico authenticates against your endpoint. See options below. |
| **Retry settings** | Maximum number of attempts and interval between attempts (exponential backoff is applied). |
| **Concurrency limit** | Maximum number of simultaneous in-flight deliveries (max: **500**). |
| **Timeout** | Maximum wait time for the endpoint's response, in seconds. |

#### Authentication methods

****OAuth2****

Provide:

  - Webhook `endpoint`
  - OAuth2 provider `URL`
  - OAuth2 provider `ClientId`
  - OAuth2 provider `Secret`

  Unico will request an access token from the provider URL using the client credentials and forward it to your endpoint as a Bearer token.

****Basic Authorization****

Provide credentials in the format `user:pass`. Unico encodes them in Base64 and sends them in the `Authorization: Basic <encoded>` header on every webhook call.

****API Key****

Two formats are supported. The string is split on the **first** colon:

  - `header:value` — sets a custom header name. Examples:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` only (no colon) — the value is sent as the `Authorization` header with no scheme prefix. Example: `abc123` → `Authorization: abc123`.

  Use the `header:value` format when you need a Bearer scheme (e.g., `Authorization:Bearer <token>`); the value-only format sends the raw value without a prefix.

****No authentication****

No credentials are sent. Only recommended for development environments — production endpoints should always require authentication.

#### Status codes

The by-client webhook uses **numeric status codes**:

| Code | Description |
|---|---|
| `2` | Divergence — the process completed with a divergence in the identity check. |
| `3` | Completed — the process completed successfully. |
| `5` | Error — the process ended due to an error. |

#### Request format

Webhook deliveries are **POST** requests to your endpoint. The body contains the transaction identifier and the numeric status code.

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### Expected response

Your endpoint must respond **synchronously**:

- **Success**: any HTTP status in the `200`–`299` range.
- **Failure**: any other status. Unico will retry with exponential backoff up to the configured maximum number of attempts, or until a `2xx` is received.

:::tip[Respond fast]
Acknowledge the webhook quickly (under your configured timeout) and process the payload asynchronously on your side. Long-running processing inside the webhook handler increases the chance of timeouts and unnecessary retries.
:::

:::warning[At-least-once delivery]
The platform guarantees at-least-once delivery — the same notification may arrive more than once. Implement idempotency on your side using the `id` field to handle duplicates safely.

For idempotency and retry handling guidance, see [Security](/developers/webhooks-and-events/security).
:::