---
title: Configuração
description: Guia passo a passo para configurar webhooks do IDCloud — autoatendimento via portal para Web e SDK, e configuração por cliente para integrações via API usando a orquestração Check (apenas Brasil).
canonical: https://developer.unico.io/pt-BR/dual-api/developers/webhooks-and-events/setup
locale: pt-BR
generated_by: markdown-export
---

O IDCloud oferece suporte a duas modalidades de webhook, dependendo de como você integra:

- **Via Portal** — para integrações Web e SDK. Configuração de autoatendimento diretamente no portal do IDCloud.
- **By client** — para integrações via API que utilizam a capability de **orquestração Check** (um fluxo assíncrono). Configurado pelo time da Unico. Disponível **apenas no Brasil**.

### Via Portal (Web & SDK)

Para registrar ou atualizar o seu endpoint de webhook, acesse o portal do IDCloud e navegue até **Configurações > Webhook**.

#### Informações necessárias

| Campo | Descrição |
|---|---|
| **URL de notificação** | Endpoint que a Unico chamará para entregar as notificações de eventos. Deve ser acessível via HTTPS. |
| **Tipo de autenticação** | Como a Unico se autentica no seu endpoint. Consulte as opções abaixo. |
| **Configurações de retry** | Número máximo de tentativas e intervalo entre tentativas (backoff exponencial é aplicado). |
| **Limite de concorrência** | Número máximo de entregas simultâneas em andamento (máx: **500**). |
| **Timeout** | Tempo máximo de espera pela resposta do endpoint, em segundos. |
| **Status a notificar** | O conjunto de estados de processo que disparam uma notificação. Atualmente fixo em `PROCESS_STATE_FINISHED`; não configurável no momento. |

## Métodos de autenticação

****OAuth2****

Forneça:

  - `endpoint` do webhook
  - `URL` do provedor OAuth2
  - `ClientId` do provedor OAuth2
  - `Secret` do provedor OAuth2

  A Unico solicitará um access token ao URL do provedor usando as credenciais do cliente e o encaminhará para o seu endpoint como Bearer token.

****Basic Authorization****

Forneça as credenciais no formato `user:pass`. A Unico as codifica em Base64 e as envia no header `Authorization: Basic <encoded>` em cada chamada de webhook.

****API Key****

Dois formatos são suportados. A string é dividida no **primeiro** dois-pontos:

  - `header:value` — define um nome de header personalizado. Exemplos:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - Somente `value` (sem dois-pontos) — o valor é enviado como header `Authorization` sem prefixo de esquema. Exemplo: `abc123` → `Authorization: abc123`.

  Use o formato `header:value` quando precisar de um esquema Bearer (ex.: `Authorization:Bearer <token>`); o formato somente com valor envia o valor bruto sem prefixo.

****Sem autenticação****

Nenhuma credencial é enviada. Recomendado apenas para ambientes de desenvolvimento — endpoints de produção devem sempre exigir autenticação.

## Estados de processo que disparam notificações

Atualmente, a Unico envia uma notificação sempre que um processo faz a transição para:

| Estado | Descrição |
|---|---|
| `PROCESS_STATE_FINISHED` | Processo finalizado — estado terminal, independente do resultado. |

:::warning[Estados podem evoluir]
O conjunto de estados notificados pela plataforma pode mudar no futuro. Torne os estados aos quais seu endpoint reage **configuráveis**, para que adicionar um novo estado não exija o redeploy do seu serviço.
:::

## Formato da requisição

As entregas de webhook são requisições **POST** para o seu endpoint. O corpo contém o identificador do processo e o estado atual.

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

:::note[`lastEvent` e `lastEventDescription`]
Esses dois campos aparecem no payload **somente quando o processo expirou** antes de o usuário concluir a jornada. Eles estão ausentes nos payloads de conclusão normais. Veja [Tipos de evento](/developers/webhooks-and-events/event-types) para o esquema completo e a lista de valores possíveis de `lastEvent`.
:::

## Resposta esperada

O seu endpoint deve responder **de forma síncrona**:

- **Sucesso**: qualquer status HTTP na faixa `200`–`299`.
- **Falha**: qualquer outro status. A Unico tentará novamente com backoff exponencial até o número máximo configurado de tentativas ou até receber um `2xx`.

:::tip[Responda rapidamente]
Confirme o recebimento do webhook rapidamente (dentro do timeout configurado) e processe o payload de forma assíncrona no seu lado. Processamento demorado dentro do handler do webhook aumenta a chance de timeouts e retentativas desnecessárias.
:::

Para orientações sobre idempotência e tratamento de retentativas, consulte [Segurança](/developers/webhooks-and-events/security).

### By client (API — Apenas Brasil)

:::info[Apenas Brasil]
O webhook by-client está disponível exclusivamente para integrações via API no Brasil que utilizam a capability de **orquestração Check** — um fluxo assíncrono onde o resultado do processo é entregue via webhook em vez de uma resposta síncrona da API.
:::

Para registrar ou atualizar o seu endpoint, entre em contato com o seu time de **CS / Onboarding**.

#### Informações necessárias

| Campo | Descrição |
|---|---|
| **URL de notificação** | Endpoint que o seu sistema expõe para receber atualizações de status. Deve ser acessível via HTTPS. |
| **Tipo de autenticação** | Como a Unico se autentica no seu endpoint. Consulte as opções abaixo. |
| **Configurações de retry** | Número máximo de tentativas e intervalo entre tentativas (backoff exponencial é aplicado). |
| **Limite de concorrência** | Número máximo de entregas simultâneas em andamento (máx: **500**). |
| **Timeout** | Tempo máximo de espera pela resposta do endpoint, em segundos. |

#### Métodos de autenticação

****OAuth2****

Forneça:

  - `endpoint` do webhook
  - `URL` do provedor OAuth2
  - `ClientId` do provedor OAuth2
  - `Secret` do provedor OAuth2

  A Unico solicitará um access token ao URL do provedor usando as credenciais do cliente e o encaminhará para o seu endpoint como Bearer token.

****Basic Authorization****

Forneça as credenciais no formato `user:pass`. A Unico as codifica em Base64 e as envia no header `Authorization: Basic <encoded>` em cada chamada de webhook.

****API Key****

Dois formatos são suportados. A string é dividida no **primeiro** dois-pontos:

  - `header:value` — define um nome de header personalizado. Exemplos:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - Somente `value` (sem dois-pontos) — o valor é enviado como header `Authorization` sem prefixo de esquema. Exemplo: `abc123` → `Authorization: abc123`.

  Use o formato `header:value` quando precisar de um esquema Bearer (ex.: `Authorization:Bearer <token>`); o formato somente com valor envia o valor bruto sem prefixo.

****Sem autenticação****

Nenhuma credencial é enviada. Recomendado apenas para ambientes de desenvolvimento — endpoints de produção devem sempre exigir autenticação.

#### Códigos de status

O webhook by-client utiliza **códigos de status numéricos**:

| Código | Descrição |
|---|---|
| `2` | Divergência — o processo foi concluído com uma divergência na verificação de identidade. |
| `3` | Concluído — o processo foi concluído com sucesso. |
| `5` | Erro — o processo encerrou devido a um erro. |

#### Formato da requisição

As entregas de webhook são requisições **POST** para o seu endpoint. O corpo contém o identificador da transação e o código de status numérico.

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

#### Resposta esperada

O seu endpoint deve responder **de forma síncrona**:

- **Sucesso**: qualquer status HTTP na faixa `200`–`299`.
- **Falha**: qualquer outro status. A Unico tentará novamente com backoff exponencial até o número máximo configurado de tentativas ou até receber um `2xx`.

:::tip[Responda rapidamente]
Confirme o recebimento do webhook rapidamente (dentro do timeout configurado) e processe o payload de forma assíncrona no seu lado. Processamento demorado dentro do handler do webhook aumenta a chance de timeouts e retentativas desnecessárias.
:::

:::warning[Entrega ao menos uma vez]
A plataforma garante entrega ao menos uma vez — a mesma notificação pode chegar mais de uma vez. Implemente idempotência no seu lado usando o campo `id` para tratar duplicatas com segurança.

Para orientações sobre idempotência e tratamento de retentativas, consulte [Segurança](/developers/webhooks-and-events/security).
:::