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.

Technically, a webhook is an HTTP POST request that Glomo sends to a URL you control, containing a JSON payload that describes what happened.

A webhook URL is a publicly accessible HTTPS endpoint on your server that is set up to receive incoming HTTP POST requests from Glomo.

When you configure a webhook in the Glomo dashboard, you provide this URL. Every time an event occurs in your account, Glomo will send the event data to that URL.

Requirements for a valid webhook URL:

• Must be publicly accessible over the internet (not localhost)
• Must use HTTPS (plain HTTP is not accepted)
• Must respond with a 200 OK status code upon successful receipt
• Must be able to handle POST requests with a JSON body

• Glomo sends webhook notifications as HTTP POST requests
• The data is delivered in JSON format
• Every webhook payload always contains two important fields:
  • entity_type — identifies what the webhook is about (e.g. payment, order, payout)
  • event_type — identifies what happened to it (e.g. success, failed, expired)

Every webhook payload follows the same top-level structure:

{
  "entity_type": "payment",
  "event_type": "success",
  "data": {
    "id": "payt_686f7cc3pe69T",
    "status": "success",
    ...
  }
}

You can set up to receive webhook events on your account in 3 simple steps.

You can verify that your webhook URL is correctly set up and reachable by using the Test Connection feature in the Glomo dashboard.

1. Save your webhook details first — Enter your Webhook URL and Secret, then click Save. The Test Connection button is only available after the webhook details have been saved.
2. Click "Test Connection" — The button is located in the top-right corner of the Webhook Edit page.
3. Glomo will send a test request to your configured webhook URL.

If the test fails, verify that:

• Your webhook URL is publicly accessible over HTTPS
• Your server is returning a 200 OK response
• There are no firewall or IP restrictions blocking Glomo's requests

Every webhook request Glomo sends is signed with your webhook secret key. This allows you to verify that the request genuinely came from Glomo and has not been tampered with in transit.

When Glomo sends a webhook, it:

1. Takes the raw JSON body of the request.
2. Applies RFC 8785 JSON canonicalization to normalize key ordering across different environments.
3. Computes an HMAC SHA-256 hash of the canonicalized body using your webhook secret key.
4. Attaches the resulting hex-encoded signature to the X-Glomopay-Signature request header.

On your server, you should:

1. Extract the signature from the X-Glomopay-Signature header in the incoming webhook request.
2. Apply RFC 8785 JSON canonicalization to the raw request body.
3. Compute the HMAC SHA-256 hash of the canonicalized body using your stored webhook secret key.
4. Compare your computed hash with the value from the header.
5. If the two values match, the webhook is authentic. If they don't match, discard the request.

Important: Never process a webhook payload without first verifying the signature. Skipping this step exposes your system to spoofed or tampered requests.

function isValidSignature($payload, $headerSignature, $secretKey) {
    $computedHash = hash_hmac('sha256', $payload, $secretKey);
    return hash_equals($computedHash, $headerSignature);
}

require 'openssl'

def is_valid_signature(payload, header_signature, secret_key)
  computed_hash = OpenSSL::HMAC.hexdigest('sha256', secret_key, payload)
  computed_hash == header_signature
end

const crypto = require('crypto');

function isValidSignature(payload, headerSignature, secretKey) {
    const computedHash = crypto.createHmac('sha256', secretKey).update(payload).digest('hex');
    return computedHash === headerSignature;
}

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_signature

If Glomo sends a webhook to your URL and does not receive a 200 OK response — whether because your server is down, too slow, returned an error, or responded with any other status code — the delivery is considered failed.

Glomo will automatically retry the webhook delivery up to 9 times, using the following back-off schedule:

If all 9 retries are exhausted without a successful 200 OK, no further delivery attempts will be made for that event.

• Return 200 OK immediately — Acknowledge receipt first, then handle processing asynchronously in a background job or queue.
• Monitor your endpoint — Set up alerting for 5xx errors or high response times on your webhook endpoint.
• Design for idempotency — Since retries can result in the same event being delivered multiple times, ensure your processing logic handles duplicate deliveries safely.