Evento Webhook

Nossa plataforma adota uma arquitetura orientada a eventos. Várias operações financeiras, como saques Pix e transações em Blockchain, dependem da aprovação de redes externas e não ocorrem instantaneamente.

Para evitar que sua aplicação precise fazer polling (consultas repetitivas de status), a DEX API empurra (pushes) atualizações de estado em tempo real para o seu servidor.

Aviso: O cadastro da URL do seu Webhook deve ser feito diretamente no Painel do Parceiro. Nossa plataforma se encarregará de assinar os envios para garantir a segurança da comunicação.

1. Dicionário de Eventos

Abaixo estão todos os eventos (enviados no campo event do payload) que a sua aplicação pode receber, agrupados pelos módulos da nossa API.

⚡ Módulo: Pix

Relacionados aos endpoints /pix/deposit e /pix/withdraw.

PIX_DEPOSIT_COMPLETED: Disparado quando um usuário paga o QR Code Pix gerado pela sua aplicação e o valor é creditado na conta.
PIX_WITHDRAW_COMPLETED: Disparado quando a transferência Pix (saque) solicitada for liquidada com sucesso no Banco Central.
PIX_WITHDRAW_FAILED: Disparado caso o saque Pix falhe (ex: chave DICT rejeitada pela instituição de destino ou falha de rede do BACEN).

🪙 Módulo: Cripto & Ledger

Relacionados aos endpoints /ledger/crypto/withdraw e rotinas de depósito de carteiras on-chain.

CRYPTO_DEPOSIT_CONFIRMED: Disparado quando um depósito em criptomoeda atinge o número mínimo de confirmações na rede e é creditado no saldo do usuário.
CRYPTO_WITHDRAW_COMPLETED: Disparado quando o saque cripto solicitado é processado pelo provedor de liquidez e minerado com sucesso na blockchain.
CRYPTO_WITHDRAW_FAILED: Disparado caso a transação blockchain falhe (ex: erro de gas ou rejeição do provedor cripto).

👤 Módulo: Usuários e Compliance (KYC)

Relacionados aos processos de nível de conta.

KYC_APPROVED: A submissão de documentos do usuário foi validada e aprovada pelo time de compliance.
KYC_REJECTED: Os documentos enviados pelo usuário foram rejeitados (necessário recomeçar o processo de KYC).
ACCOUNT_UPGRADED_TO_FULL: A conta do usuário foi promovida do nível BASIC para FULL, liberando funcionalidades limitadas como o Pix.
USER_BLOCKED: O usuário sofreu um bloqueio (geralmente acionado por políticas preventivas de Fraude/PLD).
USER_UNBLOCKED: O usuário teve o acesso reestabelecido.

💸 Módulo: Transferências Internas (P2P)

Relacionados a transferências dentro da plataforma (contas DEX).

TRANSFER_INTERNAL_RECEIVED: O usuário recebeu um pagamento instantâneo de outra conta da plataforma.
TRANSFER_INTERNAL_SENT: O usuário enviou um pagamento interno com sucesso.
PENDING_TRANSFER_CREATED: Uma transferência foi disparada para um número de telefone não cadastrado e está aguardando aceite.
PENDING_TRANSFER_CLAIMED: O destinatário (novo usuário) criou a conta e aceitou a transferência pendente.
PENDING_TRANSFER_EXPIRED: O tempo limite para o resgate expirou e os fundos foram devolvidos ao remetente.

2. O Formato do "Envelope" (JSON)

Para facilitar a padronização no seu backend, todos os eventos são enviados em uma "casca" (envelope) com o mesmo formato, independentemente do tipo de operação.

Exemplo real de Payload:

{
  "id": "0df83749-d7b8-4d56-8c43-1e5828453cc1",
  "event": "PIX_WITHDRAW_COMPLETED",
  "timestamp": "2026-06-17T15:00:00.000Z",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "amount": 10000
  }
}

A propriedade data conterá os detalhes específicos daquela transação ou usuário. Seu sistema deve rotear o comportamento com base no campo genérico event.

Cabeçalhos (Headers) Enviados: Sua aplicação receberá os seguintes headers em cada requisição:

X-Delivery-Id: Id único da entrega (mesmo do corpo).
X-Event-Type: O nome do evento em maiúsculo.
X-Signature: A assinatura criptográfica para você validar a autenticidade (veja abaixo).

3. Segurança e Assinatura (HMAC)

Para garantir que a requisição partiu genuinamente dos servidores da Ether (evitando ataques de terceiros tentando forjar depósitos ou saques), nós assinamos o payload usando seu Webhook Secret.

O Header X-Signature virá no formato: X-Signature: t=1718640000,v1=a1b2c3d4e5f6g7h8...

Como Validar a Assinatura:

Extraia o t (timestamp Unix) e o v1 (assinatura) do Header X-Signature.
Pegue o ID de entrega vindo no header X-Delivery-Id.
Concatene os três itens separando por um ponto (.): t.X-Delivery-Id.Corpo_JSON_Cru.
Gere um hash HMAC-SHA256 utilizando sua chave Webhook Secret.
Compare o Hash gerado por você em Hexadecimal com o v1 vindo da nossa requisição.

💡 Proteção contra Replay: Compare o timestamp Unix t com o horário atual do seu servidor. Nossa API rejeita assinaturas com mais de 5 minutos de diferença cronológica.

Tratamento de Erros