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 |
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"
}
}
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:
- 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;
}
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. 
