Webhooks

Webhooks are HTTP callbacks that notify your application when events occur in your Glyde account. Instead of polling the API to check transaction status, webhooks push updates to you in real-time.

Why Webhooks Matter

Webhooks are essential for production integrations because:

Real-time updates — Know immediately when a payment succeeds or a transfer completes
Reliability — Don’t miss status changes due to network issues or polling gaps
Efficiency — Reduce API calls by receiving push notifications instead of polling
Automation — Trigger fulfillment, send receipts, or update records automatically

Never rely solely on client-side redirects to confirm payments. Customers can manipulate redirect URLs or close their browser before redirecting. Always verify transaction status via webhooks.

Setting Up Webhooks

Go to Settings → API Keys & Webhook in your dashboard
Enter your webhook endpoint URL (must be HTTPS in production)
Copy your webhook signing key for signature verification

Your endpoint should be publicly accessible and respond quickly. Glyde will send POST requests to this URL when events occur.

Event Types

Event	Description	When It Fires
`collection.success`	Payment received	Customer completes a payment
`collection.failed`	Payment failed	Payment attempt fails or expires
`transfer.success`	Transfer completed	Funds delivered to recipient
`transfer.failed`	Transfer failed	Transfer could not be completed
`bill.successful`	Bill payment completed	Airtime, data, electricity or cable was delivered to the customer
`bill.failed`	Bill payment failed	The biller rejected the bill; the amount and fee are refunded to your wallet

Webhook Payload

Every webhook includes an event field identifying what happened and a data object with transaction details:

{
  "event": "collection.success",
  "data": {
    "reference": "glyde_ref_123",
    "merchant_reference": "order_456",
    "amount": 10000,
    "status": "successful",
    "fee": 100,
    "created_at": "2025-01-19T10:30:00.000000Z"
  }
}

Use merchant_reference to match the webhook to your original transaction. This is the reference you provided when creating the transaction.

Bill payment payloads

bill.* webhooks carry an extra bill object describing what was bought. For prepaid electricity, bill.token holds the meter token:

{
  "event": "bill.successful",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_reference": "bill_abc125",
    "type": "debit",
    "amount": 5000,
    "status": "successful",
    "fee": 0,
    "session_id": null,
    "created_at": "2026-10-21T10:30:00.000000Z",
    "bill": {
      "category": "electricity",
      "service_code": "ikeja-electric-prepaid",
      "customer_identifier": "04123456789",
      "customer_name": "John Doe",
      "product_code": null,
      "product_name": null,
      "token": "1234-5678-9012-3456-7890",
      "units": "42.5 kWh"
    }
  }
}

See Bill Payments for the full flow.

Verifying Webhook Signatures

Webhooks include an X-Glyde-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the webhook came from Glyde and wasn’t tampered with. To verify:

Get the raw request body (before parsing JSON)
Compute HMAC-SHA256 using your signing key
Compare your hash with the X-Glyde-Signature header

const crypto = require('crypto');

function verifySignature(payload, signature, signingKey) {
  const hash = crypto
    .createHmac('sha256', signingKey)
    .update(payload)
    .digest('hex');
  return hash === signature;
}

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, signing_key: str) -> bool:
    expected = hmac.new(
        signing_key.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

$expected = hash_hmac('sha256', $payload, $signingKey);
$valid = hash_equals($expected, $signature);

Handling Webhooks

Follow these best practices when processing webhooks:

1. Respond Quickly

Return a 200 OK status immediately, then process the webhook asynchronously. Glyde waits for a response and will retry if your endpoint times out.

2. Handle Duplicates

Webhooks may be delivered more than once. Use the reference field to implement idempotency—check if you’ve already processed a webhook before taking action.

3. Verify Before Acting

Always verify the webhook signature before processing. Additionally, consider fetching the transaction from the API to confirm its current status before fulfilling orders or releasing funds.

4. Log Everything

Store webhook payloads for debugging and audit purposes. If something goes wrong, logs help you understand what happened.

Retry Policy

If your endpoint doesn’t return a 2xx response, Glyde retries with exponential backoff:

1st retry: 5 minutes
2nd retry: 30 minutes
3rd retry: 2 hours
4th retry: 8 hours
5th retry: 24 hours

After all retries fail, the webhook is marked as failed. You can view failed webhooks in your dashboard and manually retry them.

Testing Webhooks

In sandbox mode, webhooks behave the same as production. Use tools like ngrok to expose your local development server and receive webhooks during testing.

Getting Started

Core Concepts

Guides

Why Webhooks Matter

Setting Up Webhooks

Event Types

Webhook Payload

Bill payment payloads

Verifying Webhook Signatures

Handling Webhooks

1. Respond Quickly

2. Handle Duplicates

3. Verify Before Acting

4. Log Everything

Retry Policy

Testing Webhooks

​Why Webhooks Matter

​Setting Up Webhooks

​Event Types

​Webhook Payload

​Bill payment payloads

​Verifying Webhook Signatures

​Handling Webhooks

​1. Respond Quickly

​2. Handle Duplicates

​3. Verify Before Acting

​4. Log Everything

​Retry Policy

​Testing Webhooks

Why Webhooks Matter

Setting Up Webhooks

Event Types

Webhook Payload

Bill payment payloads

Verifying Webhook Signatures

Handling Webhooks

1. Respond Quickly

2. Handle Duplicates

3. Verify Before Acting

4. Log Everything

Retry Policy

Testing Webhooks