Webhooks de Transações do Paystation

Este guia explica como o Paystation envia notificações de eventos de transação (criação, pagamento, estorno/chargeback, etc.) para os clientes por meio de webhooks e como validar as mensagens com segurança.

Visão geral

• Os webhooks são disparados para cada URL definida em Webhook Notification Urls do Client.
• Cada entrega é uma requisição POST com corpo application/json.
• Responda com HTTP 2xx para confirmar o recebimento. Respostas != 2xx ou timeouts geram novas tentativas com backoff progressivo.
• Assinaturas são calculadas com o Webhook Token configurado no Client; valide antes de processar.

Cabeçalhos enviados

• Content-Type: application/json
• X-Paystation-Event: tipo do evento (ex.: transaction.paid).
• X-Paystation-Delivery: identificador único da entrega (use para idempotência).
• X-Paystation-Signature: HMAC-SHA256 do corpo bruto usando o Webhook Token, no formato sha256=<hash_hex>.
• X-Paystation-Timestamp: ISO8601 do momento em que a mensagem foi gerada (use na verificação contra replays).

Estrutura do payload

{
  "event": "transaction.paid",
  "event_id": "wh_01HR8K8YQS4B5TM2M8",
  "attempt": 1,
  "sent_at": "2024-05-10T14:22:31Z",
  "data": {
    "transaction": {
      "id": "txn_1234567890",
      "client": "mario-trentim",
      "offer": "curso-rpn",
      "type": "card",
      "status": "paid",
      "amount": 119640,
      "currency": "BRL",
      "installments": 12,
      "customer": {
        "name": "Renata Cliente",
        "email": "renata.cliente@example.com",
        "document": "12345678901",
        "phone": "+5511999990000"
      },
      "order": {
        "summary": {
          "subTotalPrice": 99700,
          "discount": 0,
          "interest": 19940,
          "totalPrice": 119640
        }
      },
      "payment_gateway": {
        "gateway_id": "3400158",
        "acquirer_name": "pagarme_v5",
        "payment_data": {
          "installments": 12,
          "card": {
            "brand": "Mastercard",
            "last_digits": "3333"
          }
        }
      }
    }
  }
}

Observação: o payload completo pode incluir campos adicionais (endereços, bumps, cupom, etc.) dependendo da transação e integrações ativas.

Eventos de transação comuns

• transaction.created: transação registrada/gerada.
• transaction.pending: aguardando pagamento (ex.: boleto ou Pix aberto).
• transaction.paid: pagamento confirmado.
• transaction.unpaid: pagamento não confirmado/expirado.
• transaction.waiting_refund: reembolso solicitado/em processamento.
• transaction.refunded: reembolso concluído.
• transaction.chargeback: chargeback recebido ou em disputa.

Política de reenvio

• O Paystation reenvia automaticamente se a resposta não for 2xx ou em caso de timeout.
• Cada reenvio mantém o mesmo X-Paystation-Delivery (útil para idempotência) e incrementa attempt.
• Use processamento idempotente (baseado em X-Paystation-Delivery ou event_id) para evitar duplicidade.

Como validar a assinatura (HMAC-SHA256)

1. Leia o corpo bruto (sem alterar espaços/ordem de campos).
2. Calcule HMAC_SHA256(body, WEBHOOK_TOKEN) e converta para hexadecimal.
3. Compare com o valor após sha256= em X-Paystation-Signature usando comparação segura (tempo constante).
4. Opcional: rejeite mensagens com X-Paystation-Timestamp fora de uma janela de tempo aceitável para mitigar replay.

Boas práticas no consumidor

• Responder rápido (ack em 2xx) e delegar o processamento para fila/worker.
• Registrar logs por X-Paystation-Delivery e event_id para facilitar suporte.
• Validar assinatura antes de qualquer efeito colateral.
• Tratar eventos idempotentemente e suportar reentregas.
• Manter alta disponibilidade no endpoint (HTTPS recomendado).

Dicas para homologação

• Use um endpoint de staging para validar payloads e assinatura antes de ir para produção.
• Simule respostas não-2xx para verificar se sua aplicação lida bem com reentregas.