Pular para o conteúdo principal

Webhook

Markdown

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.

informação

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​

EscopoUm webhook por tenant e unidade (branch). Não existe lista: se já houver um configurado, ele é editado, não duplicado.
Ambientes separadosO 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 valerAssim que você salva.
Segurança do secretO 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 Gerencie o webhook, com o botão Configurar webhook

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

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:

TipoCampos que aparecemQuando usar
NenhumanenhumA 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 KeySecretA sua API valida uma chave fixa
Basic AuthSecretA sua API usa usuário e senha no padrão HTTP Basic
OAuth 2.0URL de autenticação, Client ID, SecretA sua API exige token. O IDCloud busca o token nessa URL e o renova sozinho
mTLSCertificado 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

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:

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

CampoO que controlaPadrão
Máximo de retentativasQuantas 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 tentativas2s
Tempo máximo (s)Intervalo máximo entre tentativas10s
Duração máxima (s)Tempo de espera por tentativa até considerar falha2s
Dobras máximasFator 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

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