Catálogo de eventos
Todos os eventos que um webhook da Clav pode receber e os campos de cada um.
Convenção de nomes
Os eventos seguem o formato <recurso>.<fato no passado>, como
wallet.verified. O recurso vem primeiro para que você consiga tratar um
domínio inteiro pelo prefixo. O verbo fica no passado porque o evento anuncia
algo que já aconteceu.
Novos eventos podem ser adicionados sem aviso. Ignore os que o seu endpoint não
reconhece e responda 2xx mesmo assim, para não gerar novas tentativas à toa.
Eventos disponíveis
| Evento | Quando é enviado |
|---|---|
wallet.verified | Uma prova de carteira foi aceita. |
wallet.failed | Uma prova de carteira foi recusada ou chegou fora do prazo. |
Eventos de carteira
Os dois eventos de carteira têm o mesmo formato de data. Eles são emitidos
pelo produto de verificação de carteira.
| Campo | Tipo | Descrição |
|---|---|---|
organizationId | string | Organização dona do desafio. |
challengeId | string | Identificador do desafio. |
externalCustomerId | string | O identificador do cliente que você enviou ao abrir o desafio. |
chain | string | EVM, BITCOIN, TRON ou SOLANA. |
address | string | Endereço normalizado que precisava ser provado. |
method | string | SIGNATURE ou MICRO_TRANSACTION. |
nonce | string | Identificador único do desafio, o mesmo de GET /v1/wallet-proofs/{nonce}. |
status | string | VERIFIED, FAILED ou EXPIRED. |
recoveredAddress | string ou null | Endereço que de fato assinou, quando foi possível obtê-lo. |
failureReason | string ou null | Motivo da falha. null em wallet.verified. |
verifiedAt | string ou null | Momento da verificação, em ISO-8601. |
verifiedWalletId | string ou null | Carteira verificada criada ou atualizada. null em wallet.failed. |
wallet.verified
{
"id": "65f0a1b2c3d4e5f60718293a-wallet.verified",
"event": "wallet.verified",
"occurredAt": "2026-09-16T12:04:11.000Z",
"data": {
"organizationId": "65e9f0a1b2c3d4e5f6071829",
"challengeId": "65f0a1b2c3d4e5f60718293a",
"externalCustomerId": "customer-8842",
"chain": "EVM",
"address": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
"method": "SIGNATURE",
"nonce": "a3f1c0d9e8b7a6f5e4d3c2b1a0998877665544332211ffeeddccbbaa99887766",
"status": "VERIFIED",
"recoveredAddress": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
"failureReason": null,
"verifiedAt": "2026-09-16T12:04:11.000Z",
"verifiedWalletId": "65f0a1b2c3d4e5f60718293b"
}
}wallet.failed
Enviado quando a assinatura é recusada ou quando chega depois do prazo. Veja
status para diferenciar os dois casos e failureReason para saber o motivo.
Um desafio que vence sem nenhuma tentativa não gera evento.
A lista de motivos está na página de verificação de
carteira.
{
"id": "65f0a1b2c3d4e5f60718293a-wallet.failed",
"event": "wallet.failed",
"occurredAt": "2026-09-16T12:04:11.000Z",
"data": {
"organizationId": "65e9f0a1b2c3d4e5f6071829",
"challengeId": "65f0a1b2c3d4e5f60718293a",
"externalCustomerId": "customer-8842",
"chain": "EVM",
"address": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
"method": "SIGNATURE",
"nonce": "a3f1c0d9e8b7a6f5e4d3c2b1a0998877665544332211ffeeddccbbaa99887766",
"status": "FAILED",
"recoveredAddress": "0xab8483f64d9c6d1ecf9b849ae677dd3315835cb2",
"failureReason": "ADDRESS_MISMATCH",
"verifiedAt": null,
"verifiedWalletId": null
}
}Use a API para liberar saques
Use os eventos para atualizar a sua interface e os seus registros. Na hora de
liberar um saque, continue consultando GET /v1/wallets, que também considera
revogações feitas depois da prova.