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

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

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

*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](/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. 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

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