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 tanto para integrações byUnico quanto byClient.
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 desta tela existir, qualquer alteração de webhook exigia abrir chamado — eram cerca de 30 chamados por mês só para isso. Agora você faz sozinho, em minutos, tanto em Homologação quanto em Produção.
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 quatro 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 |
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.
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.
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 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. 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
│ OAuth 2.0: + URL de autenticação e Client ID
└─ 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