Webhooks

Webhooks are a way of receiving push notifications from our gateway when certain events happen that are not triggered by an API request. For example, you might want to get notified when a PayTo Payment Agreement has been updated or when a PayOut transaction you have submitted has cleared into the recipient’s bank account.

When you have created a webhook subscription you will receive HTTP POST requests containing a JSON payload to the callback URL you specified in the subscription.

Types of Events

Our API currently allows you to subscribe to event notifications for the following resources:

Resource	Webhook event
Transactions	transactions
PayOuts	payouts
Customers	customers
Payment Instruments	payment_instruments
Payment Requests	payment_requests

Accepting Webhooks

Getting Started

Step 1: Create a Webhook Subscription

Create webhook subscriptions using the REST API:

POST /webhooks
Content-Type: application/json
X-Api-Key: {your-api-key}

{
    "event": "transactions",
    "url": "https://yourdomain.com/webhooks/events"
}

Create one subscription per event. Repeat the request for each event type you want to receive.

Step 2: Implement Your Webhook Endpoint

Set up an endpoint that can receive HTTP POST requests from our gateway and parse the JSON payload.

The webhook body will contain a unique id, a timestamp, a version number, an event type, and the payload data.

The payload data will contain the same response model as the resource itself. Refer to the specific resource section of the documentation for example response models.

Below is an example webhook payload structure.

{
    "id": "WQYvMI-3FUWMHlB22rW69Q",
    "reference": "YOUR-REFERENCE",
    "created": "2026-02-02T02:02:48Z",
    "version": "1.0.0",
    "event": "transactions",
    "payload": {
        "id": "RESOURCE-ID",
        "updatedDateTime": "2026-02-02T02:02:09Z",
        "result": {
            "status": "approved"
        }
    }
}

Step 3: Process Webhook Events

Your endpoint should:

• Accept HTTP POST requests with JSON body
• Verify the X-Signature header (see Verifying Events below)
• Parse the event and payload fields
• Update your systems accordingly
• Respond with HTTP 200 to acknowledge receipt

Webhook Processing Flow:

sequenceDiagram
    participant GP as GP Gateway
    participant Webhook as Your Webhook Endpoint
    participant DB as Your Database

    GP->>Webhook: POST callbackUrl (X-Signature + JSON payload)
    Webhook->>Webhook: Verify X-Signature using webhook signing key
    alt signature valid
        Webhook->>Webhook: Parse webhook.event and webhook.payload
        Webhook->>Webhook: Route to handler based on webhook.event
        Webhook->>DB: Update your system (idempotent)
        Webhook->>GP: HTTP 200 OK
    else signature invalid
        Webhook->>GP: HTTP 401 Unauthorized
    end

Verifying Events

Global Payments will sign each webhook notification using your webhook signing key, which can be retrieved by calling the Retrieve Webhook Key method of the API. The signature is an HMAC-SHA256 hash of the webhook payload using the signing key as the secret. The resulting signature is passed in the X-Signature header of the webhook.

Global Payments also supports the ability to pass as username and password in the Authorization header, should you wish to protect your endpoint from unauthenticated requests. You can configure the username and password used for authentication by calling the Update Webhook Settings method. Depending on your settings, the Basic Auth header will be sent in either the Authorization header or the X-Authorization header.

Order of Events

As the Global Payments API is asynchronous, you may occasionally receive events out of order. The updatedDateTime returned in the response can be used to confirm when the resource was last updated. If in doubt, performing a GET request against the resourceId will return the most up-to-date information on the resource.

Duplicate Events

Occasionally you may receive multiple notifications for the same event. It’s important to ensure your system is resilient to this behaviour and can handle it accordingly. One way of handling this scenario is to make your webhook handler idempotent by keeping a log of events you’ve processed and not re-processing any events you have already handled.

Polling (Fallback)

If webhooks are not feasible, you can poll the API from your server to verify transaction and payment request status.

Polling strategy (generic):

• Prefer webhooks for asynchronous resources.
• If you poll, fetch the resource that changed (based on the webhook event) and treat the returned state as the source of truth.
• If the resource references other resources by id/location, follow those links to fetch more details.

Polling Flow:

sequenceDiagram
    participant Client as Client Browser
    participant Server as Your Server
    participant API as GP API

    Client->>Server: Request status update
    Server->>API: GET /{resource}/{id}
    API-->>Server: Resource details
    Server->>Server: Verify state and apply business rules
    Server-->>Client: Return verified result

    Note over Server,API: Follow any related resource links (location/id)

Example: Payments (Transactions + Payment Requests)

The example below is a common payments verification pattern:

• GET /paymentrequests/{paymentRequestId} — confirm paymentRequestStatus and locate the related transaction.
• GET /transactions/{transactionId} — verify final result.status and confirm amount/currency.

Locating the transaction from a payment request:

• Successful payment: paymentRequestStatus is completed and transactionResult is populated with the transaction id and location.
• Failed payment: paymentRequestStatus is completed, transactionResult is not populated, and transactionAttempts is populated with the failed transaction reference.
• You can also retrieve transactions associated with a payment request via GET /transactions?paymentrequestid={paymentRequestId}.