Webhooks — Crypto

Webhooks permitem que o seu sistema receba notificações em tempo real sempre que um depósito ou saque crypto ocorrer. Quando um evento acontece, enviamos um POST HTTP para a URL que você cadastrou.

Autenticação da Requisição

Cada requisição enviada para a sua URL contém dois cabeçalhos de segurança:

Cabeçalho	Descrição
`X-Webhook-Event`	Nome do evento disparado (ex: `payment.crypto.deposit.paid`)
`X-Signature`	Assinatura HMAC-SHA256 do body completo usando o seu `api_secret`

Como verificar a assinatura

A assinatura é gerada com HMAC-SHA256 sobre o JSON completo do body enviado.

Node.js

PHP

Python

Importante: Leia o body como bytes/raw antes de fazer o parse JSON. Se você fizer o parse primeiro e serializar de volta, a ordem das chaves pode mudar e a assinatura não vai bater.

Formato do Payload

Todos os eventos seguem o mesmo envelope:

{
  "event": "nome.do.evento",
  "data": { ... },
  "timestamp": "2026-06-14T12:00:00.000Z"
}

O campo data contém os detalhes da transação.

Eventos — Depósito Crypto

`payment.crypto.deposit.created`

Disparado quando o usuário inicia um depósito e o endereço de pagamento é gerado. O pagamento ainda não foi recebido.

{
  "event": "payment.crypto.deposit.created",
  "data": {
    "event": "payment.crypto.deposit.created",
    "transaction_id": "clx3ghi789",
    "external_id": "inv-abc123",
    "type": "crypto_in",
    "amount": 200.00,
    "amount_fees": 6.00,
    "net_amount": 194.00,
    "status": "pending",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "invoice_url": "https://checkout.example.com/invoice/abc123",
    "wallet_hash": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "qr_code": "data:image/png;base64,...",
    "memo": null,
    "created_at": "2026-06-14T14:00:00.000Z",
    "updated_at": "2026-06-14T14:00:00.000Z"
  },
  "timestamp": "2026-06-14T14:00:00.000Z"
}

`payment.crypto.deposit.paid`

Disparado quando o pagamento é confirmado on-chain e o saldo é creditado ao usuário (já descontadas as taxas).

{
  "event": "payment.crypto.deposit.paid",
  "data": {
    "event": "payment.crypto.deposit.paid",
    "transaction_id": "clx3ghi789",
    "external_id": "inv-abc123",
    "type": "crypto_in",
    "amount": 200.00,
    "amount_fees": 6.00,
    "net_amount": 194.00,
    "status": "paid",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "paidAt": "2026-06-14T14:10:00.000Z",
    "created_at": "2026-06-14T14:00:00.000Z",
    "updated_at": "2026-06-14T14:10:00.000Z"
  },
  "timestamp": "2026-06-14T14:10:00.000Z"
}

`payment.crypto.deposit.failed`

Disparado quando o depósito falha (ex: transação rejeitada ou expirou na blockchain).

{
  "event": "payment.crypto.deposit.failed",
  "data": {
    "event": "payment.crypto.deposit.failed",
    "transaction_id": "clx3ghi789",
    "external_id": "inv-abc123",
    "type": "crypto_in",
    "amount": 200.00,
    "amount_fees": 6.00,
    "net_amount": 194.00,
    "status": "failed",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "created_at": "2026-06-14T14:00:00.000Z",
    "updated_at": "2026-06-14T14:30:00.000Z"
  },
  "timestamp": "2026-06-14T14:30:00.000Z"
}

`payment.crypto.deposit.cancelled`

Disparado quando o depósito é cancelado ou expirou sem pagamento.

{
  "event": "payment.crypto.deposit.cancelled",
  "data": {
    "event": "payment.crypto.deposit.cancelled",
    "transaction_id": "clx3ghi789",
    "external_id": "inv-abc123",
    "type": "crypto_in",
    "amount": 200.00,
    "amount_fees": 6.00,
    "net_amount": 194.00,
    "status": "cancelled",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "created_at": "2026-06-14T14:00:00.000Z",
    "updated_at": "2026-06-14T15:00:00.000Z"
  },
  "timestamp": "2026-06-14T15:00:00.000Z"
}

Eventos — Saque Crypto

`payment.crypto.withdraw.processing`

Disparado imediatamente quando o saque é solicitado e o saldo é debitado. O envio on-chain ainda está pendente.

{
  "event": "payment.crypto.withdraw.processing",
  "data": {
    "event": "payment.crypto.withdraw.processing",
    "transaction_id": "clx4jkl012",
    "external_id": null,
    "type": "crypto_out",
    "amount": 100.00,
    "amount_fees": 5.00,
    "net_amount": 105.00,
    "status": "processing",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "crypto_wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2026-06-14T15:00:00.000Z",
    "updated_at": "2026-06-14T15:00:00.000Z"
  },
  "timestamp": "2026-06-14T15:00:00.000Z"
}

net_amount = amount + amount_fees (total debitado do saldo). O usuário recebe amount convertido em crypto.

`payment.crypto.withdraw.completed`

Disparado quando o envio é confirmado on-chain.

{
  "event": "payment.crypto.withdraw.completed",
  "data": {
    "event": "payment.crypto.withdraw.completed",
    "transaction_id": "clx4jkl012",
    "external_id": "withdraw-xyz",
    "type": "crypto_out",
    "amount": 100.00,
    "amount_fees": 5.00,
    "net_amount": 105.00,
    "status": "paid",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "crypto_wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "paidAt": "2026-06-14T15:15:00.000Z",
    "created_at": "2026-06-14T15:00:00.000Z",
    "updated_at": "2026-06-14T15:15:00.000Z"
  },
  "timestamp": "2026-06-14T15:15:00.000Z"
}

`payment.crypto.withdraw.failed`

Disparado quando o saque falha. O saldo é estornado automaticamente (amount + amount_fees devolvidos).

{
  "event": "payment.crypto.withdraw.failed",
  "data": {
    "event": "payment.crypto.withdraw.failed",
    "transaction_id": "clx4jkl012",
    "external_id": "withdraw-xyz",
    "type": "crypto_out",
    "amount": 100.00,
    "amount_fees": 5.00,
    "net_amount": 105.00,
    "status": "failed",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "crypto_wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2026-06-14T15:00:00.000Z",
    "updated_at": "2026-06-14T15:10:00.000Z"
  },
  "timestamp": "2026-06-14T15:10:00.000Z"
}

`payment.crypto.withdraw.cancelled`

Disparado quando o saque é cancelado. O saldo é estornado automaticamente.

{
  "event": "payment.crypto.withdraw.cancelled",
  "data": {
    "event": "payment.crypto.withdraw.cancelled",
    "transaction_id": "clx4jkl012",
    "external_id": "withdraw-xyz",
    "type": "crypto_out",
    "amount": 100.00,
    "amount_fees": 5.00,
    "net_amount": 105.00,
    "status": "cancelled",
    "crypto_currency": "USDT_TRX",
    "crypto_network": "USDT_TRX",
    "crypto_wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2026-06-14T15:00:00.000Z",
    "updated_at": "2026-06-14T15:05:00.000Z"
  },
  "timestamp": "2026-06-14T15:05:00.000Z"
}

Referência de Campos

Campo	Tipo	Descrição
`transaction_id`	string	ID interno da transação na plataforma
`external_id`	string \| null	ID da transação no provedor externo. `null` enquanto o envio ainda não foi iniciado
`type`	string	`crypto_in` (depósito) ou `crypto_out` (saque)
`amount`	number	Valor em BRL solicitado pelo usuário
`amount_fees`	number	Total de taxas cobradas em BRL
`net_amount`	number	Depósito: valor creditado ao usuário (`amount - fees`). Saque: total debitado do saldo (`amount + fees`)
`status`	string	`pending`, `processing`, `paid`, `failed`, `cancelled`
`crypto_currency`	string	Código da moeda (ex: `USDT_TRX`, `SOL`, `BTC`, `ETH`)
`crypto_network`	string	Rede blockchain utilizada
`crypto_wallet`	string	Endereço de carteira do destinatário (apenas saques)
`wallet_hash`	string	Endereço gerado para receber o depósito (apenas depósitos)
`invoice_url`	string	URL da página de pagamento (apenas `deposit.created`)
`memo`	string \| null	Memo/tag obrigatório em algumas redes (TON, XRP)
`paidAt`	string \| null	ISO 8601 de quando o pagamento foi confirmado

Status das Transações

Status	Descrição
`pending`	Aguardando pagamento
`processing`	Saque solicitado, envio on-chain pendente
`paid`	Confirmado e liquidado
`failed`	Falhou — saldo estornado automaticamente quando aplicável
`cancelled`	Cancelado — saldo estornado automaticamente quando aplicável

Boas Práticas

Responda com HTTP 200 rapidamente. O servidor aguarda até 10 segundos. Se o seu processamento for demorado, salve o payload e processe de forma assíncrona.

Sempre verifique a assinatura antes de processar qualquer evento.

Trate idempotência. O mesmo evento pode ser entregue mais de uma vez em caso de falha de rede. Use transaction_id como chave de deduplicação.

Use o campo type para distinguir depósitos (crypto_in) de saques (crypto_out).

Webhook USDT

Webhooks — Crypto#

Autenticação da Requisição#

Como verificar a assinatura#

Formato do Payload#

Eventos — Depósito Crypto#

payment.crypto.deposit.created#

payment.crypto.deposit.paid#

payment.crypto.deposit.failed#

payment.crypto.deposit.cancelled#

Eventos — Saque Crypto#

payment.crypto.withdraw.processing#

payment.crypto.withdraw.completed#

payment.crypto.withdraw.failed#

payment.crypto.withdraw.cancelled#

Referência de Campos#

Status das Transações#

Boas Práticas#