Webhooks allow your application to receive real-time notifications about events that occur in your account, such as payment link creation, payment completion, or payment failures.
You can set up to receive webhook events on your account in 3 simple steps.
1
Login to your Glomopay dashboard.
→
2
Navigate to Settings > API & Webhooks.
→
3
Enter the URL where you want to receive events, add your secret key, and click Create to add your webhook.
When an event is triggered, our system sends an HTTP POST request to the webhook URL you configure on the Glomopay dashboard. Each webhook's JSON payload always includes two keys:
- entity_type: identifies the resource the webhook targets.
- event_type: specifies the event on that resource that triggered the webhook.
Your endpoint should return a 200 OK status to acknowledge receipt. If your endpoint does not respond with 200 OK, we will retry the webhook up to 9 times with back-off intervals of 1 min, 5 min, 15 min, 1 hour, 3 hours, 6 hours, 12 hours, 24 hours, and 48 hours.
To ensure the security of your webhook notifications, Glomo signs the webhook events with a secret key. You can verify the authenticity of the webhook events by validating the signature.
- Extract the signature from the
X-Glomopay-Signatureheader in the webhook request. - Apply RFC 8785 JSON canonicalization before HMAC signature generation to ensure consistent key ordering across different JSON libraries and programming languages.
- Compute the HMAC SHA-256 hash of the request body using the secret key.
- Compare the computed hash with the signature extracted from the header.
- If the two hashes match, the webhook event is authentic.
Code Examples
PHP
function isValidSignature($payload, $headerSignature, $secretKey) {
$computedHash = hash_hmac('sha256', $payload, $secretKey);
return hash_equals($computedHash, $headerSignature);
}Ruby
require 'openssl'
def is_valid_signature(payload, header_signature, secret_key)
computed_hash = OpenSSL::HMAC.hexdigest('sha256', secret_key, payload)
computed_hash == header_signature
endNode.js
const crypto = require('crypto');
function isValidSignature(payload, headerSignature, secretKey) {
const computedHash = crypto.createHmac('sha256', secretKey).update(payload).digest('hex');
return computedHash === headerSignature;
}Python
import hmac
import hashlib
def is_valid_signature(payload, header_signature, secret_key):
computed_hash = hmac.new(secret_key.encode(), payload.encode(), hashlib.sha256).hexdigest()
return computed_hash == header_signatureOrder webhooks notify you about events related to orders.
| Event Type | Description |
|---|---|
| active | The order has been created and is awaiting payment. |
| paid | The order has been paid successfully. |
| expired | The order has expired. |
| action_required | The order needs more details to be processed. |
| under_review | The order is under review. |
{
"entity_type": "orders",
"event_type": "paid",
"data": {
"id": "order_6819d8046mpKt",
"customer_id": "cust_6819d7d0lrLvP",
"document_id": null,
"status": "paid",
"currency": "USD",
"amount": 10000,
"purpose_code": "P0014",
"invoice_number": null,
"invoice_description": "",
"invoice_amount": 0,
"reference_number": "REF1234",
"product": {
"name": "product name",
"description": "product description"
},
"payment_methods": "card",
"created_at": "2025-05-06T09:36:04Z",
"updated_at": "2025-05-08T13:12:54Z",
"rfi_documents": {
"rfi_doc_id": "rfi_doc_123",
"name": "Passport"
},
"notes": {
"key1": "value1",
"key2": "value2"
}
}
}
Payment webhooks notify you about events related to payment processing.
| Event Type | Description |
|---|---|
| success | The payment has been successfully processed. |
| in_progress | The payment is being processed. |
| action_required | The payment needs more details to be processed. |
| failed | The payment has failed. |
| funds_available | Funds are available with Glomo and can be included in a payout or settlement |
The payment webhook includes three different amount fields that represent different stages of the payment flow:
| Field | Description | Example |
|---|---|---|
requested_amountrequested_currency | The original amount the merchant requested (in settlement currency, excluding customer-borne fees) | Merchant requests $1,000 USD |
payment_amountpayment_currency | The total amount the customer pays (in order currency, includes customer-borne fees) | Customer pays 3,745.80 AED (includes 1% txn fee + 1% FX fee) |
converted_amountconverted_currency | The final amount after currency conversion (in settlement currency, includes all fees) | Total amount received is $1,020 USD |
Fees Breakdown:
txn_fee: Transaction processing feefx_fee: Foreign exchange/currency conversion feereferral_fee: Referral or platform fee (if applicable)
Note on amounts: All amounts are represented in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, we will pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ï¿¥295, we will pass the value as 295.
{
"entity_type": "payment",
"event_type": "in_progress",
"data": {
"id": "payt_686f7cc3pe69T",
"payin_id": "order_686f7c8c7txqj",
"payin_type": "orders",
"customer_id": "cust_686f7c6evv6Nv", // only valid for regular businesses
"merchant_id": "merch_68cc1216xPrdU", // only valid for platform businesses
"product_name": null,
"product_description": null,
"status": "active",
"payment_amount": 374580,
"payment_currency": "AED",
"converted_amount": 102000,
"converted_currency": "USD",
"requested_amount": 100000,
"requested_currency": "USD",
"purpose_code": "P1301",
"sender_name": "SHORYA KUMAR PRADEEP",
"paid_at": null,
"country": "IND",
"fees": {
"txn_fee": {
"currency": "USD",
"amount": 1000
},
"fx_fee": {
"currency": "USD",
"amount": 1000
},
"referral_fee": {
"currency": "USD",
"amount": 0
}
},
"documents": [],
"payment_method": {
"type": "swift_transfer",
"id": "swift_686f7cc3sSnky",
"details": {
"sender_name": "Test Name",
"sender_country": "IND",
"sender_account_number": "50100116025317",
"sender_bank_name": "HDFC Bank",
"remittance_information": "Test Remittance Information"
}
},
"fee_bearer": "merchant",
"created_at": "2025-07-10T08:41:39Z",
"updated_at": "2025-07-10T08:41:52Z",
"error_code": null,
"error_description": null,
"error_message": null,
"funds_available": false
}
}Payment Link webhooks notify you about events related to payment links.
| Event Type | Description |
|---|---|
| active | The payment link has been created and is awaiting payment. |
| paid | The payment link has been paid successfully. |
| partially_paid | The payment link has been partially paid. |
| action_required | The payment link needs more details to be processed.. |
| expired | The payment link has expired. |
| under_review | The payment link is under review. |
| cancelled | The payment link has been cancelled. |
| failed | The payment link couldn't be created. |
{
"entity_type": "payment_link",
"event_type": "success",
"data": {
"id": "plink_6819d8046mpKt",
"customer_id": "cust_6819d7d0lrLvP",
"document_id": null,
"status": "paid",
"currency": "USD",
"amount": 10000,
"purpose_code": "P0014",
"expires_at": "2025-05-15T18:30:00Z",
"last_reminder_sent_at": "2025-05-06T09:36:12Z",
"invoice_amount": 0,
"invoice_description": "",
"invoice_number": null,
"payment_link": "https://glomopay.com/payment-links/plink_6819d8046mpKt",
"reminder_frequency": 0,
"created_at": "2025-05-06T09:36:04Z",
"updated_at": "2025-05-08T13:12:54Z",
"notes": {
"key1":"value1",
"key2":"value2"
}
}
}Payout webhooks notify you about payout lifecycle events.
| Event Type | Description |
|---|---|
| success | The payout has been successfully processed. |
| action_required | The payout requires more details to be processed. |
| failed | The payout has failed. |
{
"entity_type": "payout",
"event_type": "success",
"data": {
"id": "payout_6829c85fXZedP",
"beneficiary_id": "bene_681d848dLZrZK",
"source_amount": 1212,
"source_currency": "USD",
"destination_amount": 1200,
"destination_currency": "USD",
"purpose_code": "S0014",
"status": "success",
"fees": {
"fx": {},
"transaction": {
"currency": "USD",
"amount": 12
}
},
"mid_market_rate": 1,
"documents": [
{
"id": "doc_6829c85fm0s0W",
"type": "invoice",
"status": "uploaded"
}
],
"created_at": "2025-05-18T11:45:35Z",
"updated_at": "2025-05-18T11:45:41Z"
}
}
Refund webhooks notify you about refund lifecycle events.
| Event Type | Description |
|---|---|
| success | The refund has been successfully processed. |
| action_required | The refund requires more details to be processed. |
| failed | The refund failed. |
{
"entity_type": "refund",
"event_type": "success",
"data": {
"id": "refund_682c42dfkOVpL",
"payment_id": "payt_681cadccoSbsj",
"customer_id": "cust_6819d7d0lrLvP",
"amount": 10000,
"currency": "USD",
"balance_used": {
"currency": "USD",
"amount": 10000
},
"status": "success",
"reason": "Requested By Customer",
"fees": {
"fx_fees": {
"currency": "USD",
"amount": 0
},
"txn_fees": {
"currency": "USD",
"amount": 200
}
},
"documents": [],
"created_at": "2025-05-20T08:52:47Z",
"updated_at": "2025-05-20T08:53:55Z"
}
}
Settlement webhooks notify you about settlement lifecycle events.
| Event Type | Description |
|---|---|
| initiate | The settlement has been successfully initiated. |
| success | The settlement has been successfully processed. |
| action_required | The settlement requires more details to be processed. |
| failed | The settlement failed. |
{
"entity_type": "settlement",
"event_type": "success",
"data": {
"id": "setl_688774f9Iny7U",
"status": "success",
"payment_method": "swift_transfer",
"amount": 29100,
"currency": "USD",
"fees": {
"fx_fee": {
"amount": 0,
"currency": "USD"
},
"txn_fee": {
"amount": 288,
"currency": "USD"
}
},
"utr": "HDFC123456789012",
"created_at": "2025-07-28T13:02:49.572Z",
"updated_at": "2025-07-28T13:05:40.216Z"
}
}Internal Transfer webhooks notify you about events related to internal transfers between merchant accounts.
| Event Type | Description |
|---|---|
| success | The internal transfer has been successfully processed. |
| failed | The internal transfer has failed. |
{
"entity_type": "internal_transfer",
"event_type": "success",
"data": {
"id": "inttransfer_68ef608dXUXqr",
"from_merchant_id": "merch_68cc1216xPrdU",
"to_merchant_id": "merch_68cc0571y5S4h",
"owner_merchant_id": "merch_68cc0571y5S4h",
"transfer_amount": 10000,
"transfer_currency": "AED",
"reference": "Test internal transfer",
"fees": {
"txn_fee": {
"currency": "AED",
"amount": 0
},
"fx_fee": {
"currency": "AED",
"amount": 0
}
},
"error_code": null,
"error_description": null,
"created_at": "2025-10-15T08:51:25Z",
"updated_at": "2025-10-15T08:51:25Z"
}
}Subscription webhooks notify you about events related to subscriptions.
| Event Type | Description |
|---|---|
| active | The subscription is active. |
| authorized | The subscription has been authorized and recurring payments will start on the scheduled date |
| cancelled | The subscription has been cancelled and no further billing will occur. |
| completed | The subscription has run its full billing cycle and is complete. |
| expired | The subscription has expired and is no longer valid. |
| halted | The subscription has been halted and is pending manual reactivation. |
| paused | The subscription has been paused. No further payments will be charged until resumed. |
{
"entity_type": "subscription",
"event_type": "completed",
"data": {
"id": "sub_5JU9yv0lGSUP",
"customer_id": "cust_5JU9yv0lGSUP",
"product_name": "ShieldGuard Insurance",
"product_description": "Flexible, monthly insurance for belongings, travel, and digital assets, easy to manage",
"plan_name": "ShieldGuard Lite",
"plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
"reference_number": "R0001",
"status": "active",
"amount": 1000,
"currency": "USD",
"interval_type": "month",
"interval_count": 1,
"billing_cycles": 12,
"start_date": "2025-01-01",
"end_date": "2025-12-01",
"expires_at": "2025-01-07",
"next_payment_date": "2025-02-01",
"subscription_link_url": "https://glomopay.com/subscription/sub_5JU9yv0lGSUP",
"cancelled_at": "2025-01-15",
"notes": {
"key1": "value1",
"key2": "value2"
}
}
}