---
title: Configuração
description: O que a Unico precisa para configurar o webhook do Human Token no onboarding — URL, autenticação, retry, concorrência e timeout.
canonical: https://developer.unico.io/pt-BR/human-token/webhooks-and-events/setup
locale: pt-BR
generated_by: markdown-export
---

- [/pt-BR/](/pt-BR/)
- Recursos adicionais
- [Webhooks e Eventos](/pt-BR/human-token/webhooks-and-events/)
- Configuração

**Nesta página# Configuração

O time da Unico configura o webhook durante o onboarding da integração.
### Informações necessárias​

CampoDescriçã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:
EstadoDescrição`PROCESS_STATE_FINISHED`Processo finalizado — estado terminal, independente do resultado.
Estados podem evoluirO 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": "humantoken"}
```

`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](/pt-BR/human-token/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`.

Responda rapidamenteConfirme 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](/pt-BR/human-token/webhooks-and-events/security).Última atualização em 17 de out. de 2026**