Pular para o conteúdo principal

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
CampoDescrição
URL de notificaçãoEndpoint que a Unico chamará para entregar as notificações de eventos. Deve ser acessível via HTTPS.
Tipo de autenticaçãoComo a Unico se autentica no seu endpoint. Consulte as opções abaixo.
Configurações de retryNúmero máximo de tentativas e intervalo entre tentativas (backoff exponencial é aplicado).
Limite de concorrênciaNúmero máximo de entregas simultâneas em andamento (máx: 500).
TimeoutTempo máximo de espera pela resposta do endpoint, em segundos.
Status a notificarO 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:

EstadoDescrição
PROCESS_STATE_FINISHEDProcesso 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.

Última atualização em