O que é Webhook e como usar na Alfasu Pay

Se você já integrou pagamentos, provavelmente já se perguntou: "Como meu sistema sabe que o cliente pagou?" A resposta mais eficiente é o webhook.

Webhook vs polling

Polling é quando seu sistema consulta a API repetidamente para verificar se houve mudança de status. Funciona, mas consome recursos e adiciona latência.

Webhook é o oposto: a Alfasu Pay envia uma notificação HTTP para a URL que você configurou assim que algo acontece — pagamento confirmado, estorno, chargeback, etc.

Como configurar

1. Acesse o painel Alfasu Pay → Configurações → Webhooks
2. Cadastre a URL do seu endpoint (deve ser HTTPS)
3. Selecione os eventos que deseja receber
4. Guarde o webhook_secret para validação

Estrutura de um evento

{
  "id": "evt_abc123",
  "type": "pix.charge.paid",
  "created_at": "2025-01-10T14:32:00Z",
  "data": {
    "charge_id": "ch_xyz789",
    "amount": 15000,
    "paid_at": "2025-01-10T14:31:58Z"
  }
}

Validação de segurança

Nunca processe um webhook sem validar a assinatura. A Alfasu Pay envia o header X-Alfasu-Signature com um HMAC-SHA256 do payload usando seu webhook_secret.

const crypto = require('crypto')

function validateSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Boas práticas

• Responda com status 200 em até 5 segundos
• Processe eventos de forma idempotente (o mesmo evento pode ser reenviado)
• Use filas para processamento assíncrono em alto volume
• Registre todos os eventos recebidos para auditoria

Veja a documentação completa em Webhooks Pix.