Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useglyde.co/llms.txt

Use this file to discover all available pages before exploring further.

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

  1. Go to Settings → API Keys & Webhook in your dashboard
  2. Enter your webhook endpoint URL (must be HTTPS in production)
  3. 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

EventDescriptionWhen It Fires
collection.successPayment receivedCustomer completes a payment
collection.failedPayment failedPayment attempt fails or expires
transfer.successTransfer completedFunds delivered to recipient
transfer.failedTransfer failedTransfer could not be completed

​
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.

​
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:
  1. Get the raw request body (before parsing JSON)
  2. Compute HMAC-SHA256 using your signing key
  3. 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;
}

​
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.