---
title: Webhook
description: Configure para onde o IDCloud notifica o seu sistema quando uma jornada muda de estado, como ele se autentica na sua API e o que fazer quando a sua API não responde.
canonical: https://developer.unico.io/pt-BR/dual-api/product-guide/portal-idcloud/settings/webhook
locale: pt-BR
generated_by: markdown-export
---

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.

:::info
**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 Gerencie o webhook, com o botão Configurar webhook](/img/product-guide/webhook/pt-BR/01-manage-webhook.png)

*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](/img/product-guide/webhook/pt-BR/02-edit-webhook.png)

*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](/img/product-guide/webhook/pt-BR/02-edit-webhook.png)

*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](/img/product-guide/webhook/pt-BR/02-edit-webhook.png)

*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

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