Recebimento de Webhooks

Os Webhooks são notificações automáticas enviadas pela XGate para o seu sistema sempre que o status de uma transação muda (ex: um depósito via Pix foi pago, ocorreu um erro na liquidação ou um saque entrou em processamento).

Isso elimina a necessidade do seu sistema ficar consultando a API repetidamente (polling) para saber se um pagamento caiu. A XGate faz o papel apenas de mensageira: nós disparamos as informações, e o seu sistema deve estar preparado para recebê-las e tratá-las.

Configurando no Painel

É fundamental entender que a XGate não fornece uma URL de webhook. Você (ou sua equipe de desenvolvimento) precisa construir uma rota pública em seu próprio servidor para receber os dados. Após criar essa rota, você deve informá-la no painel da XGate.

Siga os passos abaixo para configurar o envio das notificações:

Acesse o menu lateral Webhooks no seu painel XGate.
Clique em + Adicionar Integração ou clique em Configurar em um slot vazio.
Preencha os campos de destino:
- Nome: Um nome de identificação interno para você (ex: "Webhook Servidor Principal").
- URL: O endereço completo do endpoint hospedado no seu servidor (ex: https://sua-empresa.com/api/webhooks/xgate).
Eventos: Selecione quais notificações você deseja que a XGate envie para esta URL. Os eventos são divididos em:
- CRYPTOCURRENCY: Transações via Crypto.
- CURRENCY: Transações via Moeda Fiduciária (Pix, incluindo aprovação, rejeição, erros, e toda a esteira de estornos/contestações).

Dica de Integração

Nossa recomendação é que você habilite todos os eventos disponíveis. Isso garante que o seu banco de dados possua um espelhamento perfeito do que está acontecendo na XGate, evitando que transações fiquem presas em status desatualizados. No entanto, a escolha final fica a seu critério.

Segurança: Whitelist de IP

Para garantir que seu sistema não sofra ataques de webhooks falsos (usuários mal-intencionados simulando que um pagamento foi aprovado), a XGate envia todas as notificações a partir de um IP Fixo Exclusivo.

Recomendamos fortemente que você configure o firewall do seu servidor ou crie uma validação em seu código para aceitar apenas requisições POST vindas do seguinte IP:

IP Oficial XGate: 107.23.39.46

Idempotência e "externalId"

Ao criar pedidos de Depósito ou Saque, você pode enviar o campo externalId. Ele possui duas funções vitais:

Prevenção de Duplicidade (Idempotência): Impede que falhas de rede ou "duplo clique" do seu cliente final gerem múltiplas transações iguais na XGate. Se forem enviadas duas requisições com o mesmo externalId, a segunda será ignorada.
Rastreabilidade: Funciona como o código único do pedido no seu sistema.

Nota: Se você enviar o externalId na criação da transação, a XGate o devolverá dentro do payload do webhook, facilitando a busca no seu banco de dados.

Como funciona o fluxo?

Você cadastra a sua URL no painel da XGate e seleciona os eventos.
Quando um dos eventos selecionados ocorre, a XGate faz uma requisição POST para a sua URL a partir do IP 107.23.39.46.
Seu sistema recebe o JSON, processa a lógica de negócio e confirma o recebimento retornando um HTTP 200 OK.

Boa Prática de Integração

Seu servidor DEVE retornar o status HTTP 200 (OK) imediatamente após receber o webhook. Essa é a prática padrão para informar à XGate que seu sistema processou a notificação com sucesso, finalizando a conexão adequadamente e evitando falhas de comunicação (timeouts) entre os servidores.

Formato da Requisição e Variações

O formato do Payload varia ligeiramente dependendo se a transação envolve apenas Fiat (Pix) ou Criptomoedas (USDT).

Método: POST

Exemplos de Payload

1. Transação Padrão (Pix BRL): Retorna o campo type especificando o método.

{
    "id": "676071f1*************",
    "customerId": "123456*************",
    "status": "PAID",
    "name": "BRL",
    "type": "PIX",
    "amount": 2,
    "operation": "DEPOSIT"
}

2. Saque (USDT convertido para Pix): O campo type é omitido nas operações que envolvem saldos cripto.

{
    "id": "676070dc*************",
    "customerId": "123456*************",
    "status": "PAID",
    "name": "USDT",
    "amount": 0.04,
    "operation": "WITHDRAW"
}

3. Depósito (Pix convertido para Crypto):

{
    "id": "676070*************",
    "customerId": "123456*************",
    "status": "PAID",
    "name": "USDT",
    "amount": 0.332,
    "operation": "DEPOSIT"
}

4. Saque (Crypto para Crypto)

{
  "id": "6a3a844fe2**************",
  "status": "PAID",
  "name": "USDT",
  "amount": 1,
  "operation": "WITHDRAW",
  "customerId": "6a1a379e1f**************",
  "txHash": "54vpJgzQ8C2ktDj7************************"
}

4. Depósito (Crypto para Crypto)

{
  "id": "6a3da45e116****************",
  "status": "PAID",
  "name": "USDT",
  "amount": 4.7,
  "operation": "DEPOSIT",
  "customerId": "6a1a379e1fe****************",
  "txHash": "mtVZznAKV6m1eEjWrWaX****************"
}

Descrição dos Campos

Campo	Tipo	Descrição
`id`	`string`	ID único da transação gerado pela XGate.
`status`	`string`	O status atual da transação (ex: `PAID`, `PROCESSING`).
`name`	`string`	A moeda base da transação (ex: `BRL`, `USDT`).
`type`	`string`	(Condicional) O método utilizado (ex: `PIX`). Geralmente ausente em transações envolvendo saldo cripto.
`amount`	`number`	O valor processado na transação.
`operation`	`string`	Define se é uma entrada ou saída (`DEPOSIT` ou `WITHDRAW`).
`customerId`	`string`	ID do cliente vinculado à transação.
`externalId`	`string`	(Opcional) O ID do pedido no seu sistema. Retornado apenas se foi enviado por você na criação da transação.
`txHash`	`string`	(Condicional) Hash da transação registrada na blockchain. Retornado apenas em operações 100% crypto.

Status Possíveis

Seu sistema deve estar preparado para processar os status de fluxo normal e os status do fluxo de estornos (Chargeback).

Fluxo Principal de Transações

Status	Significado	Ação Recomendada
PROCESSING	A transação está sendo processada.	Apenas registrar o andamento (comum em saques).
PAID	Transação concluída e paga com sucesso.	Liberar o saldo/produto e confirmar depósito ou saque.
ERROR	Falha na operação (ex: chave Pix incorreta em saques, titularidade inválida).	Avisar o usuário final sobre a falha e sugerir verificar informações cadastradas.
REJECTED	Rejeitado pela liquidante/parceiro bancário.	Raro de acontecer, tratar como falha definitiva.

Fluxo de Estornos e Contestações (Chargeback)

Status	Significado	Ação Recomendada
AWAITING_REFUND_CONTESTION	O cliente final abriu uma solicitação de estorno no banco dele. O saldo é retido.	Congelar o saldo/serviço do cliente preventivamente.
AWAITING_BANK_VEREDICT	Você enviou a defesa da contestação e estamos aguardando o banco julgar.	Aguardar resolução.
EXPIRED_DISPUTE	O prazo para enviar as provas de contestação do estorno expirou.	Registrar perda da disputa.
REFUND_CANCELED	O estorno foi cancelado pelo banco (você ganhou a disputa).	O valor retido é devolvido à sua conta.
REFUND_APPROVED	O estorno foi aprovado pelo banco (você perdeu a disputa).	O valor é devolvido ao cliente final em definitivo.

Configurando no Painel​

Segurança: Whitelist de IP​

Idempotência e "externalId"​

Como funciona o fluxo?​

Formato da Requisição e Variações​

Exemplos de Payload​

Descrição dos Campos​

Status Possíveis​

Fluxo Principal de Transações​

Fluxo de Estornos e Contestações (Chargeback)​