Webhooks

Receba notificações em tempo real sobre eventos de pagamento

O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente pela Versell para o seu servidor quando eventos importantes ocorrem, como o recebimento de um Pix ou a conclusão de uma transferência. Em vez de consultar a API repetidamente (polling), seu sistema recebe as atualizações em tempo real.

Você também pode configurar seus webhooks diretamente pelo painel do Finance (finance.versell.com.br), sem precisar fazer chamadas à API. O Finance também permite consultar o histórico de transações, acompanhar pagamentos recebidos e enviados, e verificar o status de webhooks configurados.

Webhook Cash In

O webhook de Cash In notifica seu sistema quando um Pix é recebido. Apenas transações Pix que possuem txid são notificadas. Os IPs de origem são dinâmicos — identifique a Versell pelo header customizado.

Configuração

Registre sua URL de webhook associada a uma chave Pix:

curl -X PUT https://api.pix.basspago.com.br/v2/webhook/{chave_pix} \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook/pix"
  }'

Exemplo de Payload

{
  "pix": [
    {
      "endToEndId": "E12345678202301011234abcdefghijkl",
      "txid": "fc9a43k6j20e4j3h78xb5n7c2qa3o",
      "chave": "your-pix-key@example.com",
      "valor": "100.00",
      "horario": "2024-01-15T14:30:00.000Z",
      "infoPagador": "Payment for invoice #456",
      "componentesValor": {
        "original": {
          "valor": "100.00"
        }
      }
    }
  ]
}

Os IPs de origem do webhook de Cash In são dinâmicos e podem mudar sem aviso. Não filtre por IP. Use o header X-Webhook-Secret para validar a autenticidade das notificações.

Webhook Cash Out

O webhook de Cash Out notifica seu sistema quando uma transferência é liquidada (settled) ou cancelada (cancelled).

Configuração

Registre sua URL de webhook para notificações de transferência:

curl -X POST https://pagamentos.basspago.com.br/api/v2/webhooks/transfer \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook/transfer",
    "webhookSecret": "your-secret-key"
  }'

Exemplo de Payload

{
  "event": "transfer.settled",
  "data": {
    "transferId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "endToEndId": "E12345678202301011234abcdefghijkl",
    "status": "SETTLED",
    "amount": "250.00",
    "recipientName": "John Doe",
    "recipientDocument": "***456789**",
    "pixKey": "john@example.com",
    "pixKeyType": "EMAIL",
    "createdAt": "2024-01-15T14:30:00.000Z",
    "settledAt": "2024-01-15T14:30:05.000Z"
  }
}

Segurança

A Versell envia um header X-Webhook-Secret em cada notificação de webhook. Use esse valor para validar que a requisição realmente veio da Versell e não de um terceiro malicioso.

app.post('/webhook/pix', (req, res) => {
  const receivedSecret = req.headers['x-webhook-secret'];
  const expectedSecret = process.env.WEBHOOK_SECRET;

  if (receivedSecret !== expectedSecret) {
    return res.status(401).json({ error: 'Invalid webhook secret' });
  }

  // Process the webhook payload
  const { pix } = req.body;
  console.log('Pix received:', pix);

  // Respond with 200 quickly
  res.status(200).json({ received: true });

  // Process asynchronously
  processPixPayment(pix).catch(console.error);
});

Sempre valide o header X-Webhook-Secret antes de processar qualquer notificação de webhook. Armazene o secret em uma variável de ambiente segura.

Boas Práticas

1.Responda com 200 rapidamente — Retorne HTTP 200 imediatamente ao receber o webhook. Processe os dados de forma assíncrona para evitar timeouts.
2.Processamento assíncrono — Use filas (RabbitMQ, SQS, Redis) para processar webhooks em background. Não bloqueie a resposta com lógica de negócio.
3.Trate duplicatas — Webhooks podem ser enviados mais de uma vez. Use o endToEndId ou transferId como chave de idempotência para evitar processar o mesmo evento duas vezes.
4.Lógica de retry — Se seu servidor não responder com 200, a Versell tentará reenviar a notificação. Certifique-se de que seu endpoint é idempotente.
5.Validação de segurança — Sempre valide o X-Webhook-Secret e, se possível, verifique a assinatura do payload.