Webhooks

Webhooks notify your application in real-time when events occur in GovPayPlan, such as successful payments or refunds.

How Webhooks Work

1. An event occurs in GovPayPlan (e.g., payment completed)
2. GovPayPlan sends an HTTP POST to your endpoint
3. Your server processes the event
4. Your server responds with 200 OK

Setting Up Webhooks

Create a Webhook Endpoint

1. Navigate to Settings > API > Webhooks
2. Click Add Endpoint
3. Enter your endpoint URL
4. Select events to subscribe to
5. Save

Endpoint Requirements

• Must be HTTPS
• Must respond within 30 seconds
• Must return 2xx status code
• Must be publicly accessible

Webhook Events

Payment Events

Event	Description
payment.created	Payment initiated
payment.completed	Payment successful
payment.failed	Payment declined/failed
payment.refunded	Full refund issued
payment.partially_refunded	Partial refund issued

Recurring Payment Events

Event	Description
recurring.created	Recurring payment set up
recurring.payment_completed	Scheduled payment processed
recurring.payment_failed	Scheduled payment failed
recurring.cancelled	Recurring payment cancelled

Other Events

Event	Description
refund.created	Refund initiated
refund.completed	Refund processed
dispute.created	Chargeback received

Webhook Payload

Structure

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "payment": {
      "id": "pay_xyz789",
      "amount": 100.00,
      "currency": "USD",
      "status": "completed",
      "payer": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  }
}

Headers

Header	Description
X-GPP-Signature	Signature for verification
X-GPP-Event	Event type
X-GPP-Delivery-ID	Unique delivery ID

Verifying Webhooks

Always verify webhook signatures to ensure authenticity.

Signature Verification

const crypto = require('crypto');

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-gpp-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  res.status(200).send('OK');
});

Handling Webhooks

Best Practices

1. Respond quickly: Return 200 immediately, process async
2. Handle duplicates: Use delivery ID for idempotency
3. Verify signatures: Always validate webhook authenticity
4. Log events: Keep records for debugging

Example Handler

app.post('/webhooks', async (req, res) => {
  // Verify signature first
  if (!verifyWebhook(req)) {
    return res.status(401).send('Unauthorized');
  }

  // Respond immediately
  res.status(200).send('OK');

  // Process async
  const event = req.body;

  switch (event.type) {
    case 'payment.completed':
      await handlePaymentCompleted(event.data.payment);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data.payment);
      break;
    case 'refund.completed':
      await handleRefundCompleted(event.data.refund);
      break;
  }
});

Retry Policy

If your endpoint fails to respond, GovPayPlan retries:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failures, the webhook is marked as failed.

Monitoring Webhooks

Webhook Logs

View webhook delivery history:

1. Navigate to Settings > API > Webhooks
2. Click on your endpoint
3. View Delivery History

Failed Webhooks

For failed deliveries:

• Check endpoint availability
• Verify SSL certificate
• Review response logs
• Manually retry if needed

Testing Webhooks

Test Events

Send test webhooks from the dashboard:

1. Navigate to Settings > API > Webhooks
2. Select your endpoint
3. Click Send Test Event
4. Choose event type
5. Review delivery

Local Development

For testing locally, use a tunnel service:

# Using ngrok
ngrok http 3000

# Use the https URL for your webhook
# https://abc123.ngrok.io/webhooks

Related Topics

• Authentication - Webhook secrets
• Getting Started - API overview
• Testing - Test environment