Configuração

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.

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.

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

lastEvent e lastEventDescription

Esses dois campos aparecem no payload somente quando result = expired — ou seja, 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 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.

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.

By client (API — Apenas Brasil)

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.

{
  "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.

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.

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.