Webhooks — integração e notificações em tempo real

Visão geral

O BE4 Pay envia requisições POST para a URL configurada na sua conta, com corpo JSON descrevendo o evento. Os cabeçalhos incluem metadados e, quando há segredo configurado, assinatura para validação.

Configuração

Para receber webhooks:

1. Disponibilize um endpoint POST que leia o JSON e responda com sucesso (2xx) após processar ou enfileirar.
2. Cadastre a URL, o secret HMAC e os eventos em Gerenciamento de API no painel.
3. Valide a assinatura quando o segredo estiver configurado (veja abaixo).

Cabeçalhos HTTP

Em cada entrega, a plataforma pode enviar, entre outros:

• x-webhook-event — nome do evento
• x-webhook-id — identificador da entrega
• x-webhook-timestamp — timestamp usado na assinatura (milissegundos)
• x-webhook-idempotency-key — chave para deduplicação
• x-webhook-signature — quando há segredo: sha256=<hex>

Exemplo de payload

O corpo reflete o tipo de evento. Exemplo genérico (estrutura ilustrativa):

{
  "event": "cashin.created",
  "occurred_at": "2026-04-10T16:23:14.000Z",
  "external_use": true,
  "user_id": 1,
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "PEDIDO-123",
  "amount": 100.00,
  "fee": 0.99,
  "payment_status": "PENDING"
}

Tipos de eventos (API / uso externo)

Eventos comuns disparados para integrações via credenciais de API incluem:

• cashin.created — cobrança PIX (cash-in) criada
• cashin.paid — cobrança PIX (cash-in) liquidada / paga
• cashout.created — saque / transferência PIX (cash-out) solicitada
• boleto.created — boleto emitido pela API pública
• boleto.paid — boleto liquidado
• boleto.cancelled — boleto cancelado
• boleto.expired — boleto expirado
• boleto.status_changed — outra mudança de status do boleto (API)
• bill_payment.created — pagamento de boleto enfileirado
• bill_payment.paid — boleto de terceiro liquidado
• bill_payment.failed — pagamento de boleto recusado, funding A55 ou split da taxa Vexa falhou

É possível restringir quais eventos receber conforme a configuração do endpoint (lista de eventos inscritos), quando suportado.

Validação e segurança

Com segredo configurado, o cabeçalho x-webhook-signature traz sha256=<hex>, onde <hex> é o HMAC-SHA256 do segredo sobre a string ${x-webhook-timestamp}.${corpo_bruto}— use o corpo bruto (bytes/string exata) recebido na requisição para comparar.

// Exemplo em Node.js (corpo como string bruta do request)
const crypto = require('crypto');

function isValidWebhookSignature(rawBody, timestamp, signatureHeader, secret) {
  const match = /^sha256=(.+)$/.exec(signatureHeader || '');
  if (!match) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(match[1], 'hex'), Buffer.from(expected, 'hex'));
}

Boas práticas

• Responda com 2xx somente após persistir ou enfileirar o processamento.
• Use x-webhook-idempotency-key para evitar trabalho duplicado.
• Mantenha logs das entregas para auditoria.
• Proteja o endpoint (TLS, allowlist de IP se aplicável).