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 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