←Trocar docs

Docs/Webhooks

Webhooks

Receba notificações em tempo real sobre depósitos, saques, infrações/MED e conversões.

Entrega e retentativas

  • - O envio é feito via HTTP POST com payload JSON.
  • - Respostas fora da faixa 2xx acionam novas tentativas automáticas.
  • - Recomenda-se validar a assinatura sobre o corpo bruto do POST e registrar idempotência por data.id + event.

Assinatura do payload

  • - A assinatura do payload é opcional, mas recomendada.
  • - Header enviado: X-Webhook-Signature (valor em hexadecimal, sem prefixo).
  • - Algoritmo: HMAC-SHA256 sobre o corpo bruto da requisição (a mesma sequência de bytes do JSON enviado no POST), interpretada como UTF-8.
  • - Não valide com JSON.stringify(JSON.parse(rawBody)): a ordem das chaves e espaços podem divergir e a assinatura deixa de bater.
  • - Segredo: chave de assinatura exibida ao criar ou consultar o webhook no painel.
  • - Em frameworks que fazem parse automático do body, use middleware de leitura bruta (raw) antes do parser para obter a string exata. 
import { createHmac, timingSafeEqual } from 'node:crypto'

/**
 * rawBody: string ou Buffer exatamente como recebido no POST (antes de JSON.parse).
 * Depois de retornar true, faça JSON.parse(rawBody) para processar o evento.
 */
export const verifyWebhookSignature = (
  rawBody: string | Buffer,
  headerSignature: string,
  secret: string
) => {
  const bodyString = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8')
  const expected = createHmac('sha256', secret).update(bodyString, 'utf8').digest('hex')

  const providedBuffer = Buffer.from(String(headerSignature || ''), 'utf8')
  const expectedBuffer = Buffer.from(expected, 'utf8')

  if (providedBuffer.length !== expectedBuffer.length) {
    return false
  }

  return timingSafeEqual(providedBuffer, expectedBuffer)
}

Eventos de depósito USDT

EventoStatusDescrição
DEPOSIT_PENDINGpendingDepósito criado, QR Code disponível, aguardando pagamento.
DEPOSIT_PAIDpaidDepósito USDT confirmado e creditado na conta.
DEPOSIT_EXPIREDexpiredQR Code expirou sem pagamento.
DEPOSIT_CANCELEDcanceledDepósito cancelado antes da liquidação.

{
  "data": {
    "id": "01KFAKEDEPOSIT000000000000",
    "amount": 99.97,
    "feeAmount": 1.25,
    "netAmount": 97.37,
    "type": "deposit",
    "method": "usdt",
    "currency": "usdt",
    "network": "trx",
    "address": "TJq2t8gHmwgymsJy447pqx5kTfKFW5wcsp",
    "customer": {
      "id": "01KFAKECUSTOMER000000000000",
      "name": "João Silva Santos",
      "email": "[email protected]",
      "phone": "+5511987654321",
      "document": "12345678909"
    },
    "metadata": {
      "number": 1,
      "string": "yes",
      "boolean": true
    },
    "reference": "5b7f08f2-1f2f-4d59-a03f-6c6ca0f9fca2",
    "expiresAt": "2026-03-30T13:15:00.000Z",
    "createdAt": "2026-03-30T13:00:00.000Z",
    "updatedAt": "2026-03-30T13:00:00.000Z",
    "invoiceUrl": "https://checkout.aurepay.com.br/payment/01KFAKEDEPOSIT000000000000",
    "status": "pending",
    "qrCode": {
      "payload": "TJq2t8gHmwgymsJy447pqx5kTfKFW5wcsp",
      "imageEncoded": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAAB...[TRUNCATED]"
    }
  },
  "event": "DEPOSIT_PENDING"
}

Eventos de saque USDT

EventoStatusDescrição
WITHDRAW_PENDINGpendingSaque solicitado, aguardando processamento.
WITHDRAW_PROCESSINGprocessingSaque em processamento pela instituição financeira.
WITHDRAW_PAIDpaidSaque pago ao destinatário.
WITHDRAW_FAILEDfailedSaque USDT falhou por dados inválidos da carteira ou indisponibilidade operacional.
WITHDRAW_CANCELEDcanceledSaque cancelado pelo administrador.

{
  "data": {
    "id": "01KFAKEWITHDRAW00000000000",
    "amount": 99.97,
    "feeAmount": 1.25,
    "totalAmount": 104.36,
    "type": "withdraw",
    "method": "usdt",
    "currency": "usdt",
    "network": "trx",
    "address": "TJq2t8gHmwgymsJy447pqx5kTfKFW5wcsp",
    "networkFee": 1.8,
    "customer": {
      "id": "01KFAKECUSTOMER000000000000",
      "name": "João Silva Santos",
      "email": "[email protected]",
      "phone": "+5511987654321",
      "document": "12345678909"
    },
    "metadata": {
      "number": 1,
      "string": "yes",
      "boolean": true
    },
    "reference": "bb0fb995-9fd9-4f8e-bec9-6389b9a4f8d7",
    "createdAt": "2026-03-30T13:10:00.000Z",
    "updatedAt": "2026-03-30T13:10:00.000Z",
    "status": "pending"
  },
  "event": "WITHDRAW_PENDING"
}

Eventos de conversão

EventoStatusDescrição
CONVERSION_PENDINGpendingConversão criada e aguardando evolução do fluxo.
CONVERSION_PROCESSINGprocessingConversão em processamento.
CONVERSION_PAIDpaidConversão finalizada com sucesso.
CONVERSION_FAILEDfailedConversão falhou durante o processamento.
CONVERSION_EXPIREDexpiredConversão expirada por timeout do fluxo.
CONVERSION_CANCELEDcanceledConversão cancelada manualmente.

{
  "data": {
    "id": "01KFAKECONVERSION000000000",
    "type": "conversion",
    "source": {
      "type": "balance",
      "asset": "usdt",
      "amount": 35,
      "feeAmount": 1.75,
      "netAmount": 33.25
    },
    "target": {
      "type": "balance",
      "asset": "brl",
      "amount": 177.06,
      "price": 5.325
    },
    "reference": "17bfaf35-cf64-438b-89d8-f6e78f9ad15a",
    "createdAt": "2026-03-30T13:15:00.000Z",
    "updatedAt": "2026-03-30T13:15:00.000Z",
    "status": "pending"
  },
  "event": "CONVERSION_PENDING"
}