Webhooks

🎣 Configuração de Webhooks

Endpoints de Webhook

POST /webhooks/stripe
POST /webhooks/paypal  
POST /webhooks/mercadopago

Configuração no Dashboard

1. Acesse o painel administrativo

2. Vá para "Configurações" > "Webhooks"

3. Adicione a URL: https://api.paymentgateway.com/webhooks/{provider}

4. Configure os eventos desejados

📡 Eventos Suportados

Stripe

Evento	Descrição
payment_intent.succeeded	Pagamento bem-sucedido
payment_intent.payment_failed	Pagamento falhou
charge.dispute.created	Chargeback criado
invoice.payment_succeeded	Fatura paga

PayPal

Evento	Descrição
PAYMENT.CAPTURE.COMPLETED	Pagamento capturado
PAYMENT.CAPTURE.DENIED	Pagamento negado
BILLING.SUBSCRIPTION.ACTIVATED	Assinatura ativada

MercadoPago

Evento	Descrição
payment	Status de pagamento alterado
plan	Plano de assinatura alterado
subscription	Assinatura alterada

🔐 Validação de Assinatura

Stripe

const stripe = require('stripe');

app.post('/webhooks/stripe', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  
  try {
    const event = stripe.webhooks.constructEvent(
      req.body, 
      sig, 
      process.env.STRIPE_WEBHOOK_SECRET
    );
    
    // Process event
    handleStripeEvent(event);
    res.status(200).send('OK');
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

PayPal

function validatePayPalWebhook(headers, body, webhookId) {
  const cert = await getPayPalCert(headers['PAYPAL-CERT-ID']);
  return verifySignature(body, headers['PAYPAL-TRANSMISSION-SIG'], cert);
}

MercadoPago

function validateMercadoPagoWebhook(req) {
  const signature = req.headers['x-signature'];
  const requestId = req.headers['x-request-id'];
  
  const expectedSignature = generateMPSignature(
    req.body, 
    requestId, 
    process.env.MERCADOPAGO_WEBHOOK_SECRET
  );
  
  return signature === expectedSignature;
}

📝 Estrutura de Payload

Formato Padronizado

{
  "id": "evt_123456",
  "type": "payment.succeeded",
  "provider": "stripe",
  "created_at": "2024-12-12T10:30:00Z",
  "data": {
    "payment_id": "pay_123456",
    "amount": 100.00,
    "currency": "BRL",
    "status": "succeeded",
    "metadata": {}
  },
  "raw_event": { /* payload original do provedor */ }
}

Exemplo Stripe

{
  "id": "evt_1234567890",
  "object": "event",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "amount": 10000,
      "currency": "brl",
      "status": "succeeded"
    }
  }
}

🔄 Retry Logic

Política de Retry

• Tentativas: 5 tentativas máximas

• Backoff: Exponencial (1s, 2s, 4s, 8s, 16s)

• Timeout: 30 segundos por tentativa

Status de Webhook

Status	Descrição
pending	Aguardando processamento
processing	Em processamento
processed	Processado com sucesso
failed	Falha no processamento
ignored	Ignorado (evento não suportado)

📊 Monitoramento

Logs de Webhook

SELECT 
  provider,
  event_type,
  status,
  COUNT(*) as count,
  AVG(retry_count) as avg_retries
FROM webhooks_log 
WHERE created_at >= NOW() - INTERVAL '24 hours'
GROUP BY provider, event_type, status;

Métricas

• Taxa de sucesso por provedor

• Tempo médio de processamento

• Número de retries por evento

• Eventos mais frequentes

🧪 Testes de Webhook

Webhook de Teste

curl -X POST http://localhost:3000/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1640995200,v1=abc123..." \
  -d '{
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_test_123",
        "status": "succeeded"
      }
    }
  }'

Simulação de Eventos

Use as ferramentas de cada provedor:

• Stripe: Stripe CLI stripe listen --forward-to localhost:3000/webhooks/stripe

• PayPal: PayPal Developer Dashboard > Webhooks Simulator

• MercadoPago: MercadoPago Developer Tools

⚠️ Troubleshooting

Problemas Comuns

1. Signature Validation Failed

   • Verificar secret do webhook

   • Confirmar que está usando raw body

   • Validar timezone/timestamp

2. Webhook Not Received

   • Verificar firewall/proxy

   • Confirmar URL está acessível publicamente

   • Verificar logs do provedor

3. Duplicate Processing

   • Implementar idempotência

   • Verificar se webhook está configurado múltiplas vezes

---

Documentação atualizada: December 2024