Pular para o conteúdo principal

Webhooks

Oiça eventos em tempo real para manter o seu sistema em sincronia com o PaysGator.

Visão Geral​

Os webhooks permitem que o PaysGator envie notificações em tempo real para o seu servidor quando ocorrem eventos.

Eventos Suportados​

EventoDescrição
payment.successAcionado quando um pagamento é concluído com sucesso.
payment.failedAcionado quando uma tentativa de pagamento falha.
subscription.createdAcionado quando uma nova subscrição é criada.
subscription.deletedAcionado quando uma subscrição é cancelada.
withdraw.completedAcionado quando um levantamento é concluído.
withdraw.failedAcionado quando um levantamento falha.

Estrutura do Webhook​

Todos os pedidos de webhook seguem este envelope padrão:

{
  "event": "payment.success",
  "eventId": "evt_uuid_v4",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": { ... }
}

Segurança​

O PaysGator envia um cabeçalho X-Paysgator-Signature com cada pedido de webhook. Esta é uma assinatura HMAC-SHA256 do corpo do pedido utilizando o seu Segredo do Webhook (Webhook Secret).

Exemplos de Payload​

Pagamento com Sucesso (payment.success)​

{
  "event": "payment.success",
  "eventId": "evt_123...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "paymentId": "uuid-v4",
    "transactionId": "uuid-v4",
    "subscriptionId": "uuid-v4",
    "service": "paymentLink",
    "companyId": "uuid-v4",
    "amount": 100.00,
    "currency": "USD",
    "status": "SUCCESS",
    "customerEmail": "john@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "externalTransactionId": "order_123"
  }
}

Subscrição Criada (subscription.created)​

{
  "event": "subscription.created",
  "eventId": "evt_456...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "subscriptionId": "uuid-v4",
    "companyId": "uuid-v4",
    "planId": "uuid-v4",
    "customerEmail": "john@example.com",
    "amount": 50.00,
    "currency": "USD",
    "status": "ACTIVE",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}

Levantamento Concluído (withdraw.completed)​

{
  "event": "withdraw.completed",
  "eventId": "evt_789...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "withdrawId": "uuid-v4",
    "companyId": "uuid-v4",
    "amount": 500.00,
    "currency": "USD",
    "status": "SUCCESS",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}

Verificar Assinaturas​

const crypto = require('crypto');

app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-paysgator-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.PAYSGATOR_WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature === expectedSignature) {
    const webhook = req.body;
    if (webhook.event === 'payment.success') {
      console.log('Pagamento com sucesso:', webhook.data.transactionId);
    }
  }

  res.status(200).send('OK');
});