Webhooks

Listen for real-time events to keep your system in sync with PaysGator.

Overview

Webhooks allow PaysGator to send real-time notifications to your server when events occur.

Supported Events

Event	Description
payment.success	Triggered when a payment is successfully completed.
payment.failed	Triggered when a payment attempt fails.
subscription.created	Triggered when a new subscription is created.
subscription.deleted	Triggered when a subscription is canceled.
withdraw.completed	Triggered when a withdrawal is finished.
withdraw.failed	Triggered when a withdrawal fails.

Webhook Structure

All webhook requests follow this standard envelope:

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

Security

PaysGator sends a X-Paysgator-Signature header with every webhook request. This is an HMAC-SHA256 signature of the request body using your Webhook Secret.

Payload Examples

Payment Success (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"
  }
}

Subscription Created (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"
  }
}

Withdrawal Completed (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"
  }
}

Verifying Signatures

Node.js

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('Payment success:', webhook.data.transactionId);
    }
  }

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