Webhooks
Receba na sua aplicação, em tempo real, os eventos da sua organização na Clav, com entrega assinada e novas tentativas automáticas.
O que são
Um webhook é um endereço HTTPS da sua aplicação que a Clav chama sempre que algo acontece na sua organização. O aviso chega no momento do evento, e a sua aplicação não precisa consultar a API periodicamente.
Assinados
Cada requisição leva uma assinatura HMAC-SHA256 que prova que veio da Clav e não foi alterada.
Com novas tentativas
Se o seu endpoint estiver fora do ar, a entrega é repetida automaticamente.
Filtráveis
Cada webhook recebe só os eventos que você escolher.
Para quem é este guia
Para administradores de organização e para quem desenvolve a integração que vai receber os eventos.
Criando um webhook
Abra a aba Webhooks
Nas configurações da organização, vá até a aba Webhooks. Só administradores conseguem criar e remover webhooks.
Clique em Novo webhook
Informe a URL do endpoint. Ela precisa usar HTTPS e estar acessível pela internet pública.
Escolha os eventos
Marque os eventos que esse endpoint deve receber. Deixe todas as caixas desmarcadas para receber todos os eventos, inclusive os que forem criados no futuro.
Guarde o segredo
Ao clicar em Criar webhook, a plataforma exibe o segredo de assinatura. Copie e guarde num cofre de segredos: é com ele que o seu servidor confere as assinaturas.
O segredo aparece uma única vez
Não há como consultar o segredo depois. Se perdê-lo, remova o webhook e crie outro.
Você pode ter mais de um webhook na mesma organização. Cada evento é entregue a todos os que o assinam, de forma independente.
O que chega no seu endpoint
A Clav faz um POST com corpo JSON e estes cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
content-type | application/json |
x-clav-event | Nome do evento, por exemplo wallet.verified. |
x-clav-delivery | Identificador da entrega. Use para descartar duplicatas. |
x-clav-signature | Assinatura no formato t=<timestamp>,v1=<hex>. |
O corpo tem sempre o mesmo envelope. O conteúdo de data depende do evento:
{
"id": "65f0a1b2c3d4e5f60718293a-wallet.verified",
"event": "wallet.verified",
"occurredAt": "2026-09-16T12:04:11.000Z",
"data": { }
}O catálogo de eventos descreve o data de cada
um, e a página de verificação da assinatura
mostra como validar a requisição.
Como responder
Responda com qualquer status 2xx em até 10 segundos. Se o processamento for
demorado, grave o evento numa fila sua, responda logo e processe depois.
| Resposta do seu endpoint | O que a Clav faz |
|---|---|
2xx | Considera entregue. |
408 ou 429 | Tenta de novo. |
Outros 4xx | Desiste. O erro é tratado como recusa definitiva. |
5xx, timeout ou falha de conexão | Tenta de novo. |
3xx | Tenta de novo. Redirecionamentos não são seguidos. |
Novas tentativas
Cada entrega tem até 5 tentativas. O intervalo entre elas começa em 5 segundos e dobra a cada falha.
Antes de cada tentativa, a Clav relê a configuração do webhook. Remover o webhook ou tirar o evento da lista vale já para a próxima tentativa, sem esperar as pendentes acabarem.
Entrega pelo menos uma vez
Um mesmo evento pode chegar mais de uma vez, por exemplo quando o seu endpoint
processa a requisição mas a resposta se perde no caminho. O valor de
x-clav-delivery (igual ao id do corpo) se repete nesses casos. Guarde os
identificadores já processados e ignore os repetidos.
A ordem de chegada também não é garantida. Use occurredAt quando a ordem
importar.
Restrições do endpoint
Por segurança, a URL do webhook precisa:
- usar
https://; - ter um nome de domínio completo, não um nome local;
- resolver apenas para endereços IP públicos.
Endereços internos (localhost, redes privadas, .local, .internal) são
recusados na criação. A verificação se repete a cada entrega, então um domínio
que passe a apontar para um IP privado deixa de receber eventos.
Para testar na sua máquina, use um túnel com endereço HTTPS público.
Perguntas frequentes
Como troco o segredo de um webhook?
Crie um novo webhook com a mesma URL, atualize o segredo no seu servidor e remova o antigo. Durante a troca, o seu endpoint vai receber cada evento duas vezes, uma por webhook, cada uma com a sua assinatura.
Posso mudar a URL de um webhook existente?
Não pela plataforma. Crie um webhook com a nova URL e remova o antigo.
O que acontece com os eventos se nenhum webhook estiver configurado?
Nada é enfileirado. Os eventos continuam disponíveis na plataforma e pela API, mas não são reenviados quando um webhook for criado depois.
Arquitetura dos relatórios regulatórios
Os dois modelos de operação dos relatórios ao Banco Central: o agente que roda na infraestrutura da PSAV e o modelo gerenciado pela Clav.
Verificar a assinatura
Como confirmar que uma requisição de webhook veio da Clav e não foi alterada nem reenviada por terceiros.