Webhooks

Webhook Documentation

Receive real-time notifications when events occur in your PAYGabo account. Webhooks send POST requests to your server with event data.

How Webhooks Work

1. Event Occurs

A payment completes, a refund is issued, or any other tracked event happens in your account.

2. We Send a POST

PAYGabo sends an HTTP POST request to your registered webhook URL with the event payload.

3. You Verify & Process

Verify the signature, process the event, and respond with a 2xx status code.

Webhook Payload

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2025-08-23T14:31:12Z",
  "data": {
    "id": "pay_xyz789",
    "amount": 150.00,
    "currency": "GHS",
    "method": "momo",
    "phone": "+233501234567",
    "reference": "order_123",
    "status": "completed",
    "completed_at": "2025-08-23T14:31:12Z"
  }
}

Event Types

Subscribe to specific events when registering your webhook endpoint.

Event	Description
`payment.completed`	A payment has been successfully processed.
`payment.failed`	A payment attempt has failed.
`payment.pending`	A payment is awaiting processing.
`refund.completed`	A refund has been successfully issued.
`refund.failed`	A refund attempt has failed.
`settlement.completed`	A settlement batch has been paid out.

Signature Verification

Every webhook request includes an X-PayGabo-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request came from PAYGabo.

Never skip signature verification in production. This prevents replay attacks and ensures your webhook endpoint only processes authentic PAYGabo events.

Node.js — Signature Verification

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

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

// In your webhook handler:
const signature = req.headers["x-paygabo-signature"];
const isValid = verifyWebhookSignature(
  req.body,
  signature,
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: "Invalid signature" });
}

// Process the webhook event
const event = JSON.parse(req.body);
console.log("Received:", event.type);

Retry Policy

If your endpoint returns a non-2xx status code or times out, we retry the delivery with exponential backoff.

Maximum Attempts

Total delivery attempts per event

Backoff Strategy

Exponential

1m, 5m, 30m, 2h, 24h between retries

Retry Schedule

11 min

25 min

330 min

42 hours

524 hours

Ready to set up webhooks?

API Reference