Webhooks

Webhooks são notificações HTTP POST enviadas para o seu servidor quando ocorrem eventos importantes em nossa plataforma. Eles permitem que você seja notificado automaticamente sobre mudanças de status em pedidos, saques e outras operações.

Eventos Suportados

Nossa plataforma envia webhooks para os seguintes eventos:

order.created: Um novo pedido foi gerado
order.paid: Um pedido foi pago com sucesso
order.expired: Um pedido expirou sem pagamento
order.cancelled: Um pedido foi cancelado
withdrawal.completed: Um saque foi processado e concluído
withdrawal.failed: Um saque falhou ao ser processado

Configuração

Você pode configurar a URL de recebimento de webhooks no seu painel de controle da plataforma. A URL deve ser acessível publicamente via HTTPS.

Para desenvolvimento local, você pode usar ferramentas como ngrok ou similar para expor seu servidor local publicamente.

Formato do Webhook

Exemplo: Confirmação de Pagamento

Quando um pedido é pago, você receberá uma requisição POST no formato:

{
  "event": "order.paid",
  "order_id": "ord_123456789",
  "status": "paid",
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "pix",
  "paid_at": "2024-01-15T10:30:00Z",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "document": "12345678900"
  },
  "metadata": {
    "custom_field": "custom_value"
  }
}

Exemplo: Saque Concluído

Quando um saque é concluído:

{
  "event": "withdrawal.completed",
  "withdrawal_id": "wth_123456789",
  "status": "completed",
  "amount": 5000,
  "currency": "BRL",
  "pix_key": "usuario@exemplo.com",
  "completed_at": "2024-01-15T14:05:00Z"
}

Exemplo: Pedido Criado

Quando um novo pedido é criado:

{
  "event": "order.created",
  "order_id": "ord_123456789",
  "status": "pending",
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "pix",
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-15T11:00:00Z"
}

Segurança

Autenticação via Header Authorization

Todas as requisições de webhook incluem um header Authorization com o token configurado na plataforma:

Authorization: Bearer SEU_TOKEN_WEBHOOK

Validação no seu servidor:

// Node.js/Express exemplo
app.post('/webhook', (req, res) => {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (token !== process.env.WEBHOOK_TOKEN) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Processar webhook
  const event = req.body;
  handleWebhookEvent(event);

  res.status(200).json({ received: true });
});

Autenticação via X-Signature

Alternativamente, você pode validar a assinatura do webhook usando o header X-Signature:

X-Signature: sha256=abc123def456...

Validação no seu servidor:

const crypto = require('crypto');

function validateSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return `sha256=${digest}` === signature;
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = req.body;

  if (!validateSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Processar webhook
  const event = JSON.parse(payload);
  handleWebhookEvent(event);

  res.status(200).json({ received: true });
});

IMPORTANTE: Sempre valide a origem dos webhooks antes de processá-los. Nunca processe webhooks sem validação adequada, pois isso pode expor sua aplicação a ataques.

Processamento de Webhooks

Boas Práticas

Responda rapidamente: Sempre retorne um status HTTP 200 o mais rápido possível (dentro de 2-3 segundos)
Processe assincronamente: Para operações demoradas, processe o webhook em background
Idempotência: Implemente verificação de duplicatas usando o order_id ou withdrawal_id
Logs: Mantenha logs de todos os webhooks recebidos para debugging

Exemplo de Implementação

// Exemplo completo de processamento de webhook
const express = require('express');
const app = express();

// Middleware para validar token
function validateWebhookToken(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (token !== process.env.WEBHOOK_TOKEN) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  next();
}

// Endpoint de webhook
app.post('/webhook', express.json(), validateWebhookToken, async (req, res) => {
  const event = req.body;

  // Responder rapidamente
  res.status(200).json({ received: true });

  // Processar em background
  setImmediate(async () => {
    try {
      await handleWebhookEvent(event);
    } catch (error) {
      console.error('Erro ao processar webhook:', error);
      // Implementar retry logic se necessário
    }
  });
});

// Handler de eventos
async function handleWebhookEvent(event) {
  switch (event.event) {
    case 'order.paid':
      await handleOrderPaid(event);
      break;
    case 'order.expired':
      await handleOrderExpired(event);
      break;
    case 'withdrawal.completed':
      await handleWithdrawalCompleted(event);
      break;
    default:
      console.log('Evento não tratado:', event.event);
  }
}

async function handleOrderPaid(event) {
  // Atualizar status do pedido no banco de dados
  // Enviar e-mail de confirmação
  // Atualizar saldo, etc.
  console.log(`Pedido ${event.order_id} foi pago!`);
}

async function handleOrderExpired(event) {
  // Atualizar status do pedido
  // Notificar o cliente, etc.
  console.log(`Pedido ${event.order_id} expirou!`);
}

async function handleWithdrawalCompleted(event) {
  // Atualizar status do saque
  // Notificar o usuário, etc.
  console.log(`Saque ${event.withdrawal_id} foi concluído!`);
}

Retry e Timeout

Nossa plataforma tenta entregar webhooks até 3 vezes com intervalos exponenciais:

Primeira tentativa: Imediata
Segunda tentativa: Após 5 minutos
Terceira tentativa: Após 30 minutos

Se todas as tentativas falharem, o webhook será marcado como falho e você precisará consultar o status manualmente via API.

Para garantir que você não perca nenhum evento, implemente também polling periódico da API como backup.

Testando Webhooks

Para testar webhooks localmente durante o desenvolvimento:

Use uma ferramenta como ngrok para expor seu servidor local

Configure a URL do ngrok na plataforma

Teste os eventos manualmente ou aguarde eventos reais

# Exemplo com ngrok
ngrok http 3000

# Use a URL fornecida: https://abc123.ngrok.io/webhook

Próximos Passos

Configure seu endpoint de webhook na plataforma
Implemente a validação de segurança
Teste com eventos reais
Consulte a Referência de API para mais detalhes sobre os eventos

Webhooks

Use uma ferramenta como ngrok para expor seu servidor local

On this page