Skip to main content

Webhook CRYPTO

Cadastre a URL com o tipo CRYPTO. O cadastro continua na API de Contas; a entrega dos eventos é feita pelo processador de webhooks.

Endpoint: POST /webhooks/CRYPTO
Scope: webhook.write

curl --location 'https://secureapi.onz.finance/api/v2/webhooks/CRYPTO' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "uri": "https://parceiro.exemplo.com/hooks/crypto",
    "enabled": true
  }'

O path é case-insensitive (crypto também vale). Comportamento de retentativa é o mesmo dos demais webhooks da API de Contas. Veja Configurando Webhook.

Sem destino CRYPTO ativo, o broker não quebra a jornada: o enqueue retorna vazio e a ordem/carteira segue.

Eventos​

O corpo enviado ao parceiro:

{
  "type": "crypto.wallet.registered",
  "data": {
    "walletId": "88",
    "accountId": 99,
    "networkCode": "ETH",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "verificationStatus": "PENDING_VERIFICATION"
  }
}
typeQuandoDeduplicação (reference)
crypto.wallet.registeredCarteira cadastrada. Sem apelido no payload.crypto-wallet-{walletId}-registered
crypto.wallet.first_purchasePrimeiro BUY SETTLED daquela carteira.crypto-wallet-{walletId}-first_purchase
crypto.order.updatedToda transição de status da ordem (inclui expire, settle e cancel de DRAFT). EXECUTED pode trazer txHash.crypto-order-{id}-{from}-{to}-{updatedAtMs}
crypto.order.settledLiquidação BUY/SELL, além do order.updated sanitizado. Pode trazer title/body.crypto-order-settled-{id}-{updatedAtMs}

Reopen da mesma transição não colide com o ciclo anterior: o updatedAtMs muda. Retry da mesma transição reusa o updated_at persistido.

crypto.wallet.first_purchase​

{
  "type": "crypto.wallet.first_purchase",
  "data": {
    "walletId": "88",
    "accountId": 99,
    "orderId": "22222222-2222-4222-8222-222222222222",
    "networkCode": "ETH",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "assetSymbol": "USDT",
    "amountBrl": "100.00",
    "amountAsset": "18.180000"
  }
}

crypto.order.updated​

Campos nulos de carteira/hash não são enviados (só entram quando há valor).

{
  "type": "crypto.order.updated",
  "data": {
    "orderId": "22222222-2222-4222-8222-222222222222",
    "accountId": 99,
    "operation": "BUY",
    "status": "APPROVED",
    "previousStatus": "PENDING_OPERATOR",
    "assetSymbol": "USDT",
    "networkCode": "ETH",
    "amountBrl": "100.00",
    "amountAsset": "18.180000",
    "destinationWalletId": "88",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }
}

crypto.order.settled​

{
  "type": "crypto.order.settled",
  "data": {
    "orderId": "22222222-2222-4222-8222-222222222222",
    "accountId": 99,
    "operation": "BUY",
    "status": "SETTLED",
    "previousStatus": "EXECUTED",
    "assetSymbol": "BTC",
    "networkCode": "BTC",
    "amountBrl": "100.00",
    "amountAsset": "0.00030000",
    "title": "Compra liquidada",
    "body": "Sua compra de BTC (R$ 100,00) foi concluída.",
    "txHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

No BUY, title/body podem interpolar o total debitado (líquido + taxa de rede), enquanto amountBrl permanece o valor da ordem. SELL usa copy de crédito na conta. txHash só entra quando é público; não há destinationWalletId neste evento.

Jornada completa: CaaS na API de Contas. Endpoints: Carteiras, cotações e ordens.