Webhooks

Receive real-time server-to-server notifications when payout status changes.

For bank payouts, PayGo saves status notifications and delivers them through the server scheduler. Configure your public HTTPS callback or webhook URL in the merchant panel. Failed deliveries retry with increasing delays up to one hour. Duplicate deliveries are possible: deduplicate by event_id (also in X-Webhook-Id). A later refund confirmation has a new event ID.

Payout Events

Webhook Payload

{
  "event": "payout.success",
  "reference_id": "PAY-2024-001",
  "payout_id": "POXXXXXXXXXXXX",
  "amount": 1000,
  "platform_fee": 15,
  "total_debited": 1015,
  "status": "success",
  "utr": "123456789012",
  "timestamp": "2024-06-02T14:35:00+00:00"
}

Signature Verification

Bank payout notifications use X-Webhook-Signature-Version: v2. Verify X-Webhook-Signature as HMAC-SHA256 of the exact raw request body using your active merchant Secret Key. Do not re-encode JSON before verification. Legacy events still use the API key and have no version header.

$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, getenv('PAYGO_SECRET_KEY'));
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'])) {
    http_response_code(401); exit;
}