Configuração

Para configurar um webhook no Unico IDCloud, forneça seu endpoint, o método de autenticação e a política de retry. A configuração é realizada pelo time da Unico — entre em contato com o seu time de CS / Onboarding para registrar ou atualizar um 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. Todos os campos são obrigatórios.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

Para o schema completo do payload e a lista de valores de lastEvent, consulte Tipos de evento.

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.