Pular para o conteúdo
Alfasu Pay

Webhooks Pix

Configure e valide webhooks para receber notificações de pagamentos Pix em tempo real.

Webhooks permitem que seu sistema seja notificado automaticamente quando um pagamento Pix é confirmado, expira ou é estornado.

Eventos disponíveis

| Evento | Descrição | |---|---| | pix.charge.paid | Pagamento confirmado | | pix.charge.expired | Cobrança expirou sem pagamento | | pix.charge.refunded | Estorno processado |

Configuração

  1. Acesse Painel → Configurações → Webhooks
  2. Adicione a URL do seu endpoint (HTTPS obrigatório em produção)
  3. Selecione os eventos Pix
  4. Salve o webhook_secret gerado

HTTPS obrigatório

Em produção, apenas URLs HTTPS são aceitas. Certificados autoassinados não são suportados.

Payload do evento

Quando um pagamento é confirmado, você receberá:

{
  "id": "evt_abc123",
  "type": "pix.charge.paid",
  "created_at": "2025-03-15T14:32:00Z",
  "data": {
    "charge_id": "ch_xyz789",
    "amount": 15000,
    "paid_at": "2025-03-15T14:31:58Z",
    "payer": {
      "name": "Maria Silva",
      "document": "12345678900"
    }
  }
}

Validando a assinatura

Cada requisição inclui o header X-Alfasu-Signature. Valide antes de processar:

Respondendo ao webhook

Seu endpoint deve:

  1. Validar a assinatura
  2. Processar o evento (de forma idempotente)
  3. Retornar status 200 OK em até 5 segundos

Reenvio automático

Se seu endpoint não responder com 2xx, a Alfasu Pay reenvia o evento com backoff exponencial por até 72 horas.

Testando no sandbox

Simule um pagamento no painel sandbox e verifique se seu endpoint recebe o evento pix.charge.paid. Use ngrok para testes locais.