Webhook
O Webhook é como o IDCloud avisa o seu sistema, automaticamente, quando algo acontece numa jornada de verificação de identidade. Em vez de o seu sistema ficar perguntando "já terminou?", o IDCloud chama a sua API no momento em que o evento ocorre.
Nesta tela você define o endereço da sua API, como o IDCloud se autentica nela e o que acontece quando ela não responde.
Para quem é: clientes que querem receber o resultado das jornadas automaticamente, sem consultar. Vale para todos os tipos de integração.
O que muda no seu sistema: ele passa a receber uma notificação a cada mudança de estado, em vez de precisar consultar o IDCloud.
Onde fica: Portal IDCloud → menu lateral Configurações → aba Webhook.
Antes de começar
Permissão de acesso
Seu usuário precisa ter o perfil de Configurador — o mesmo que dá acesso à Customização da Jornada. Se a aba Webhook não aparece, fale com o administrador da sua conta.
Como a configuração é aplicada
| Escopo | Um webhook por tenant e unidade (branch). Não existe lista: se já houver um configurado, ele é editado, não duplicado. |
| Ambientes separados | O Portal de Homologação configura o webhook de UAT; o de Produção, o de Produção. Configurar um não afeta o outro. |
| Quando passa a valer | Assim que você salva. |
| Segurança do secret | O secret é criptografado e nunca mais exibido em texto plano. Na tela ele aparece sempre mascarado. |
O que ter em mão
- A URL HTTPS da sua API que vai receber as notificações. Ela precisa estar de pé e aceitando requisições antes de você salvar.
- As credenciais que a sua API espera, conforme o método de autenticação escolhido (veja o Passo 3).
- Se a sua API tem limite de capacidade, o número de requisições por segundo que ela suporta.
O que decidir antes
Duas decisões técnicas dependem de quem cuida da sua API, não de quem opera o Portal. Vale alinhar antes de abrir a tela:
- Qual método de autenticação a sua API exige.
- Se você vai ajustar as retentativas ou deixar no padrão. O padrão funciona para a maioria dos casos.
Passo a passo
Passo 1 — Abra a aba Webhook
No Portal IDCloud, clique no ícone de engrenagem (Configurações) no menu lateral e selecione a aba Webhook.
Se você ainda não tem webhook configurado, a tela mostra "Sem webhooks criados" e um botão Criar webhook. Se já tem, a tela mostra o card Seu webhook com o endpoint, o tipo de autenticação e o secret mascarado, além do botão Configurar webhook para editar.

Card "Seu webhook" com endpoint, tipo de autenticação e secret mascarado.
Passo 2 — Informe a URL da sua API
Clique em Criar webhook (ou Configurar webhook, se já existe um) e preencha o campo URL do cliente (Endpoint), em "Informações do cliente".
É o endereço para onde o IDCloud vai enviar as notificações. Precisa ser HTTPS.
Aponte para um endereço que já esteja no ar. O IDCloud passa a chamar essa URL assim que você salva. Se ela ainda não existe, as primeiras notificações vão falhar e consumir as retentativas antes de o seu time perceber.

Campo de endpoint, com o texto de apoio sobre o requisito de HTTPS.
Passo 3 — Escolha como o IDCloud se autentica na sua API
Em "Autenticação", selecione o Tipo de autenticação. São cinco opções, e cada uma pede campos diferentes:
| Tipo | Campos que aparecem | Quando usar |
|---|---|---|
| Nenhuma | nenhum | A sua API não exige autenticação. Só use se ela tiver outra proteção — sem autenticação, qualquer um que descobrir a URL pode enviar dados para ela |
| API Key | Secret | A sua API valida uma chave fixa |
| Basic Auth | Secret | A sua API usa usuário e senha no padrão HTTP Basic |
| OAuth 2.0 | URL de autenticação, Client ID, Secret | A sua API exige token. O IDCloud busca o token nessa URL e o renova sozinho |
| mTLS | Certificado de cliente, Chave privada, CA do servidor (opcional) | A sua API só aceita chamadas de clientes que apresentam um certificado (TLS mútuo). O IDCloud apresenta o certificado que você fornece em cada notificação |
Em OAuth 2.0, a URL de autenticação é o endereço onde o IDCloud busca o token — não é a URL que recebe as notificações. São endereços diferentes, e trocá-los é o erro mais comum nesta tela.
O Secret é gravado criptografado. Ao editar um webhook existente, o campo aparece vazio: preencher sobrescreve o secret atual, e deixar em branco mantém o que já estava lá.
Confirme o método com quem cuida da sua API antes de salvar. Autenticação errada não gera erro na tela — gera notificação que falha silenciosamente depois, e você só descobre quando um resultado não chegar.

Campo Tipo de autenticação e os campos de credencial correspondentes.
Configurando o mTLS
Com o mTLS, o IDCloud se identifica para a sua API apresentando um certificado de cliente (TLS mútuo), em vez de enviar uma chave, uma senha ou um token. A sua API precisa estar configurada para pedir esse certificado e confiar em quem o emitiu. Ao selecionar mTLS, aparecem três campos:
| Campo | O que fornecer |
|---|---|
| Certificado de cliente (PEM) | A cadeia de certificados em formato PEM, começando pelo certificado folha. Adicione os certificados intermediários depois do seu, para que a sua API consiga associar o certificado a uma autoridade em que ela confia |
| Chave privada (PEM) | A chave que forma par com o certificado, em formato PEM e sem senha. Ela é gravada criptografada e nunca mais é exibida |
| CA do servidor (PEM, opcional) | Só se o próprio certificado da sua API for assinado por uma autoridade certificadora privada. Sem ela, o IDCloud confia nas autoridades certificadoras públicas |
Você pode escolher um arquivo .pem ou colar o texto. Cada campo aceita até 20.000 caracteres.
Algumas regras para conhecer antes de escolher o mTLS:
- A URL precisa ser HTTPS, e a sua API precisa aceitar TLS 1.2 ou superior.
- Depois de salvo, o tipo fica bloqueado. O tipo de autenticação não pode ser trocado por outro nesta tela. Para trocar de método, acione o suporte da Unico.
- Nenhuma outra credencial é enviada. O mTLS não pode ser combinado com API Key, Basic Auth ou OAuth 2.0 no mesmo webhook.
- Redirecionamentos contam como falha. O IDCloud não os segue, então aponte a URL para o endereço final.
Passo 4 — Ajuste as retentativas, se precisar
A seção Configuração de retentativas é opcional e vem desligada. Ative o seletor só se você precisar mudar o comportamento padrão.
Ao ativar, aparecem seis campos:
| Campo | O que controla | Padrão |
|---|---|---|
| Máximo de retentativas | Quantas vezes o IDCloud tenta de novo antes de desistir | — |
| Limite de Taxa (req/s) | Máximo de notificações por segundo. Reduza se a sua API tiver capacidade limitada | — |
| Tempo mínimo (s) | Intervalo mínimo entre tentativas | 2s |
| Tempo máximo (s) | Intervalo máximo entre tentativas | 10s |
| Duração máxima (s) | Tempo de espera por tentativa até considerar falha | 2s |
| Dobras máximas | Fator de crescimento do intervalo entre tentativas (backoff) | 5 |
O comportamento combinado é: o IDCloud tenta, espera o tempo mínimo, tenta de novo, e vai aumentando o intervalo conforme as dobras máximas até o tempo máximo — repetindo até o máximo de retentativas. Cada tentativa individual desiste após a duração máxima.
Mexa no Limite de Taxa antes de mexer no resto. Se a sua API cai sob carga, o problema é vazão, não retentativa — e aumentar retentativas nesse cenário piora, porque multiplica as chamadas. Reduza a taxa primeiro.
Aumentar o Máximo de retentativas não substitui uma API estável. Retentativa cobre indisponibilidade momentânea. Se a sua API falha com frequência, o ajuste aqui só atrasa o momento em que você perde a notificação.

Os seis campos de retentativa, exibidos ao ativar o seletor.
Passo 5 — Salve
Clique em Salvar. Cancelar descarta tudo e mantém a configuração anterior.
O IDCloud valida a URL de token antes de permitir salvar, quando o método é OAuth 2.0. Com o mTLS, ele valida, em vez disso, o certificado e a chave: os dois precisam estar em formato PEM, a chave não pode ter senha e precisa corresponder ao certificado, e o certificado precisa estar dentro do período de validade.
Depois de salvar, o card Seu webhook mostra o endpoint e o tipo de autenticação. O secret aparece mascarado e não é mais recuperável pela tela — se você perder o valor, precisa cadastrar um novo.
Faça um teste real antes de considerar pronto. Inicie uma jornada em Homologação e confirme que a notificação chegou na sua API. A tela confirma que a configuração foi salva, não que a sua API recebeu.
Perguntas frequentes
Posso cadastrar mais de um webhook? Não. É um webhook por tenant e unidade. Se já existe um, ele é editado — não há como criar um segundo.
Configurei em Homologação. Já vale para Produção? Não. Os ambientes são independentes: o Portal de Homologação configura o webhook de UAT, e o de Produção configura o de Produção. Você precisa repetir a configuração no Portal de Produção.
Como vejo o secret que cadastrei? Não é possível. Ele é criptografado ao salvar e exibido sempre mascarado. Se você perdeu o valor, cadastre um novo pelo campo Secret — preenchê-lo sobrescreve o anterior.
Editei o webhook mas não quero trocar o secret. O que faço? Deixe o campo Secret em branco. O valor atual é mantido.
Como substituo o certificado mTLS antes que ele expire? Edite o webhook. O certificado e a chave privada aparecem mascarados. Forneça o novo certificado e a nova chave privada — os dois são obrigatórios, mesmo que só um tenha mudado — e a CA do servidor de novo, se você usar uma. Depois, salve. O IDCloud passa a usar o novo certificado dentro de cerca de 5 minutos, então mantenha o anterior válido por um pouco mais do que isso antes de revogá-lo. Se você não mexer nos três campos, o certificado atual continua em uso.
Posso trocar de mTLS para outro tipo de autenticação? Não nesta tela: depois de salvo, o tipo fica bloqueado. Acione o suporte da Unico para remover a configuração do webhook e depois crie-a de novo com o novo método.
Como excluo um webhook? A tela não oferece exclusão. Para remover a configuração, acione o suporte da Unico. Se o objetivo é só parar de receber ou trocar o destino, edite a URL.
Salvei e as notificações não chegam. Confira, nesta ordem: a URL está correta e é HTTPS; a sua API está no ar; o método de autenticação é o que ela espera; e o secret foi digitado corretamente. Com o mTLS, confira também se a sua API confia em quem emitiu o certificado, se o certificado não expirou e se a CA do servidor está preenchida, caso o certificado da sua API venha de uma autoridade certificadora privada. Falha de autenticação não aparece como erro nesta tela — ela acontece na entrega.
Qual a diferença entre "Duração máxima" e "Tempo máximo"? "Tempo máximo" é o maior intervalo de espera entre duas tentativas. "Duração máxima" é quanto o IDCloud espera por uma tentativa antes de considerá-la falha.
Preciso de webhook se já consulto o resultado pela API? Não é obrigatório, mas evita que o seu sistema fique consultando. Se você já tem uma rotina de consulta funcionando, o webhook é uma otimização, não um requisito.
Resumo rápido
Portal IDCloud
└─ Configurações (engrenagem no menu lateral)
└─ Aba Webhook
├─ Informações do cliente ... URL do cliente (Endpoint), HTTPS
├─ Autenticaç ão .............. Nenhuma | API Key | Basic Auth | OAuth 2.0 | mTLS
│ OAuth 2.0: + URL de autenticação e Client ID
│ mTLS: + Certificado de cliente, Chave privada, CA do servidor (opcional)
└─ Retentativas (opcional) .. Máximo de retentativas
Limite de Taxa (req/s)
Tempo mínimo (2s) · Tempo máximo (10s)
Duração máxima (2s) · Dobras máximas (5)
Um webhook por tenant e unidade · UAT e Produção independentes · Secret nunca exibido · Cancelar · Salvar