Webhooks
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.
Setting Up Webhooks
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.
Handling Webhooks
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.
Retries
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 5 times with back-off intervals of 1 min, 2 min, 5 min, 10 min, and 30 min.
Security
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.
Verifying 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_signaturePayment Webhooks
Payment webhooks notify you about events related to payment processing.
| Event Type | Description |
|---|---|
| payment.success | The payment has been successfully processed. |
| payment.in_progress | The payment is being processed. |
| payment.failed | The payment has failed. |
Sample Payload
{
"entity_type": "payment",
"event_type": "in_progress",
"data": {
"id": "payt_686f7cc3pe69T",
"payin_id": "order_686f7c8c7txqj",
"payin_type": "orders",
"customer_id": "cust_686f7c6evv6Nv",
"product_name": null,
"product_description": null,
"status": "active",
"payment_amount": 35322,
"payment_currency": "USD",
"converted_amount": 35322,
"converted_currency": "USD",
"purpose_code": "P1301",
"sender_name": "SHORYA KUMAR PRADEEP",
"paid_at": null,
"country": "IND",
"fees": {
"txn_fee": {
"currency": "USD",
"amount": 0
},
"fx_fee": {
"currency": "USD",
"amount": 0
},
"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
}
}
Payment Link Webhooks
Payment Link webhooks notify you about events related to payment links.
| Event Type | Description |
|---|---|
| payment_link.pending | The payment link has been created and is awaiting payment. |
| payment_link.success | The payment link has been paid successfully. |
| payment_link.partially_paid | The payment link has been partially paid. |
| payment_link.expired | The payment link has expired. |
| payment_link.rejected | The payment link was rejected. |
| payment_link.cancelled | The payment link has been cancelled. |
| payment_link.failed | The payment link couldn't be created. |
Sample Payload
{
"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"
}
}
Payout Webhooks
Payout webhooks notify you about payout lifecycle events.
| Event Type | Description |
|---|---|
| payout.success | The payout has been successfully processed. |
| payout.action_required | The payout requires more details to be processed. |
| payout.failed | The payout has failed. |
Sample Payload
{
"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
Refund webhooks notify you about refund lifecycle events.
| Event Type | Description |
|---|---|
| refund.success | The refund has been successfully processed. |
| refund.action_required | The refund requires more details to be processed. |
| refund.failed | The refund failed. |
Sample Payload
{
"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
Settlement webhooks notify you about settlement lifecycle events.
| Event Type | Description |
|---|---|
| settlement.initiate | The settlement has been successfully initiated. |
| settlement.success | The settlement has been successfully processed. |
| settlement.action_required | The settlement requires more details to be processed. |
| settlement.failed | The settlement failed. |
Sample Payload
{
"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"
}
}