Hotwallets

Webhooks

Esta secao explica como a plataforma envia eventos para sistemas externos em tempo real. Os webhooks permitem acompanhar mudancas importantes, como atualizacoes de transacoes e vaults, sem precisar consultar a API continuamente.

Conceitos rápidos

A API pública eventos para URLs cadastradas e assina cada entrega com HMAC SHA-256.

Headers enviados ao destino:

  • content-type: application/json
  • x-webhook-signature
  • x-webhook-event
  • x-webhook-id

Formato da entrega

O corpo enviado para o destino do webhook segue este formato:

{
  "eventId": "uuid-ou-id-unico",
  "eventType": "transaction.updatéd",
  "occurredAt": "2026-03-26T12:00:00.000Z",
  "payload": {
    "transactionId": "uuid",
    "status": "Success"
  }
}

Event groups usados na API

Os grupos observados no código são:

  • transaction
  • vault
  • balance

Criar um webhook vinculado ao API user autenticado.

Endpoint: POST /webhooks Autenticação

Exige bearer token com permissão webhook:write.

Body

{
  "eventGroup": "transaction",
  "targetUrl": "https://example.com/webhooks"
}

Retorno

Retorna o webhook criado.

Campos principais:

  • id
  • apiUserId
  • eventGroup
  • targetUrl
  • secret
  • status
  • createdAt
  • updatedAt

Listar os webhooks do API user atual.

Endpoint: GET /webhooks Autenticação

Exige bearer token com permissão webhook:read.

Retorno

Array de webhooks do usuário atual.

Listar o histórico de entregas de um webhook específico do usuário atual.

Endpoint: GET /webhooks/:webhookId/deliveries Autenticação

Exige bearer token com permissão webhook:read.

Parâmetros de rota

  • webhookId UUID do webhook.

Query params

  • status Filtra por status da entrega.
  • eventType Filtra por tipo de evento.

Retorno

Array de entregas.

Campos principais por item:

  • id
  • webhookId
  • eventId
  • eventType
  • payloadJson
  • attemptCount
  • status
  • responseStatus
  • responseBody
  • lastAttemptAt
  • createdAt

Consultar uma entrega específica.

Endpoint: GET /webhooks/deliveries/:deliveryId Autenticação

Exige bearer token com permissão webhook:read.

Retorno

Retorna a entrega completa, incluindo payloadJson e dados de resposta.

Reenviar manualmente uma entrega de webhook.

Endpoint: POST /webhooks/deliveries/:deliveryId/replay Autenticação

Exige bearer token com permissão webhook:write.

Retorno

Retorna a entrega atualizada após a nova tentativa.

Observações

  • A API faz até 3 tentativas por replay.
  • O campo status de entrega pode ficar como pending, retrying, delivered ou failed.

Criar um webhook global, sem vínculo com um API user.

Endpoint: POST /admin/webhooks Autenticação

Exige token de admin.

Body

Mesmo formato do endpoint de criação comum.

Listar todos os webhooks cadastrados.

Endpoint: GET /admin/webhooks Autenticação

Exige token de admin.

Excluir um webhook e suas entregas registradas.

Endpoint: DELETE /admin/webhooks/:id Autenticação

Exige token de admin.

Parâmetros de rota

  • id UUID do webhook.