Webhook Integration Guide

Overview

UseePay uses webhooks to send real-time event notifications to your HTTPS endpoints.

When a business event occurs, UseePay generates a webhook event, finds the matching webhook configurations, and sends an HTTP POST request to each matching endpoint.

Business event occurs
    ↓
UseePay generates a webhook event
    ↓
UseePay matches the merchant, application, and event type
    ↓
UseePay sends the event to the matching endpoint or endpoints
    ↓
Your endpoint verifies and processes the event

UseePay currently supports the following webhook API versions:

2026-09

2026-04

2024-10-10

For new integrations, use API version 2026-09.

Choose an API version

The API version determines the delivery request format and the available webhook configuration capabilities.

Capability	`2026-09`	`2026-04`	`2024-10-10`
Delivery Content-Type	`application/json`	`application/json`	`application/x-www-form-urlencoded`
Request body	Standard JSON object	Standard JSON object	JSON string in the `data` form field
Single-application webhook	Yes	Yes	Yes
Multiple applications in one configuration	Yes	No	No
Merchant-level webhook	Yes	No	No
Multiple enabled endpoints for one application	Yes	No	No
Update the webhook scope	Yes	No	No
Recommended for new integrations	Yes	No	No

Use:

2026-09 for all new integrations and multiple-endpoint configurations;

2026-04 when maintaining an existing JSON-based, single-application integration;

2024-10-10 only when maintaining an existing form-encoded integration.

Common integration process

Regardless of the selected API version:

Configure a public HTTPS endpoint.

Create a webhook and subscribe to the required event types.

Verify the signature of each webhook request.

Return an HTTP 2xx response as soon as the event is received.

Process time-consuming business logic asynchronously.

Implement idempotency using the Event ID.

Tolerate duplicate and out-of-order delivery.

Test the integration in the UseePay test environment.

Webhook event structure

A webhook event contains the following fields:

Field	Type	Description
`id`	string	Unique Event ID beginning with `evt_`. Use this value as the idempotency key.
`name`	string	Event name in `object.event_type` format.
`data`	object	Business object associated with the event.

Example:

{
  "id": "evt_79bdd43e4d0f464694fa433a5d467980",
  "name": "payment_intent.succeeded",
  "data": {
    "id": "pi_1234567890",
    "object": "payment_intent",
    "merchant_no": "50000000000xxxx",
    "app_id": "store-a.example.com",
    "amount": 10000,
    "currency": "USD",
    "status": "succeeded",
    "metadata": {}
  }
}

The structure of data depends on the event type. Your integration should ignore unknown fields because additional fields may be added over time.

For the complete event list, see Supported Webhook Events.

API version 2026-09

Configuration model

Version 2026-09 uses a standard JSON request body and introduces a flexible webhook configuration model.

It supports:

multiple enabled webhook endpoints for the same application;

one webhook configuration covering multiple applications;

merchant-level webhooks covering all applications under the merchant;

simultaneous matching of application-level and merchant-level webhooks;

delivery to every matching endpoint; and

updating the webhook scope.

Webhook scopes

Version 2026-09 supports three scope types.

Scope	Configuration	Events received
Single application	One concrete AppId	Events generated by the specified application
Multiple applications	Multiple AppIds separated by commas	Events generated by any listed application
Merchant	`app_id` is `*`	Events generated by any application under the merchant

Single-application scope

{
  "app_id": "store-a.example.com"
}

Multiple-application scope

{
  "app_id": "store-a.example.com,store-b.example.com"
}

Merchant-level scope

{
  "app_id": "*"
}

Specify the scope when creating a webhook

Specify the scope in exactly one of the following ways.

Use the `x-app-id` header

Use x-app-id for a single-application webhook:

When x-app-id is provided:

it must contain one concrete AppId;

it cannot contain commas;

it cannot be *; and

app_id must be omitted from the request body.

Use `app_id` in the request body

Omit x-app-id and use app_id in the request body for:

one application;

multiple applications; or

merchant-level scope.

{
  "app_id": "store-a.example.com,store-b.example.com"
}

Do not send x-app-id and Body app_id in the same create request.

`app_id` rules

The following rules apply to Body app_id:

The value is required when x-app-id is not provided.

Use an ASCII comma to separate multiple AppIds.

Do not include spaces or other whitespace.

Empty AppIds are not allowed.

Duplicate AppIds are not allowed.

* must be used by itself.

Every concrete AppId must belong to the authenticated merchant.

One webhook configuration can contain up to 50 AppIds.

Valid examples:

store-a.example.com
store-a.example.com,store-b.example.com
*

Invalid examples:

store-a.example.com, store-b.example.com
store-a.example.com,store-a.example.com
store-a.example.com,
*,store-a.example.com

Create a single-application webhook

You can specify a single application using x-app-id:

Alternatively, omit x-app-id and specify one AppId in the request body:

Create a multiple-application webhook

Create a merchant-level webhook

A merchant-level webhook receives matching events from every application under the merchant.

Endpoint limits

The following limits apply to enabled webhook configurations:

Limit	Maximum
Enabled webhooks matching one application scope	5
Enabled merchant-level webhooks	5
Enabled webhook configurations for one merchant	16
AppIds in one webhook configuration	50

A multiple-application webhook:

counts as one webhook configuration toward the merchant total; and

occupies one endpoint slot for every application included in its scope.

For example, a webhook configured for:

store-a.example.com,store-b.example.com

occupies one slot for store-a.example.com and one slot for store-b.example.com.

Disabled webhooks do not receive events and are not counted toward the enabled webhook limits.

The limits are validated when:

a webhook is created with status enabled;

a disabled webhook is enabled; or

the scope of an enabled webhook is changed.

Event matching and delivery

When an event occurs for an application, UseePay finds every enabled webhook that:

belongs to the same merchant;

contains the event's AppId in its application scope, or has merchant-level scope; and

subscribes to the event type, or subscribes to ["*"].

UseePay sends a separate HTTP POST request to every matching endpoint.

Example configuration:

Webhook	Scope	Subscribed event
Endpoint A	`store-a.example.com`	`payment_intent.succeeded`
Endpoint B	`store-a.example.com,store-b.example.com`	`payment_intent.succeeded`
Endpoint C	`*`	`payment_intent.succeeded`

If store-a.example.com generates payment_intent.succeeded:

Endpoint A receives the event.

Endpoint B receives the event.

Endpoint C receives the event.

If store-b.example.com generates the same event:

Endpoint B receives the event.

Endpoint C receives the event.

Event ID across multiple endpoints

All deliveries generated from the same business event use the same Event ID, even when the event is sent to multiple matching endpoints.

Delivery retries also use the same Event ID.

If multiple webhook configurations point to the same URL, that URL may receive the same Event ID more than once.

Always implement idempotency using the Event ID.

Delivery request format

Version 2026-09 uses application/json.

{
  "id": "evt_79bdd43e4d0f464694fa433a5d467980",
  "name": "payment_intent.succeeded",
  "data": {
    "id": "pi_1234567890",
    "object": "payment_intent",
    "merchant_no": "50000000000xxxx",
    "app_id": "store-a.example.com",
    "amount": 10000,
    "currency": "USD",
    "status": "succeeded",
    "metadata": {}
  }
}

The app_id delivery header identifies the application that generated the business event.

It does not contain the comma-separated scope saved in the webhook configuration. For an application event, it is not *, even when the event is delivered through a merchant-level webhook.

Verify the signature against the raw JSON request body before parsing or modifying it.

Update the webhook scope

For a 2026-09 webhook, update the scope by sending app_id in the request body:

{
  "app_id": "store-a.example.com,store-c.example.com"
}

To change the webhook to merchant-level scope:

{
  "app_id": "*"
}

When app_id is omitted, the existing scope remains unchanged.

The x-app-id header does not update the scope of an existing 2026-09 webhook. Use Body app_id to change the scope.

All scope and endpoint limits are revalidated when the scope or enabled status changes.

API version 2026-04

Configuration model

Version 2026-04 uses a standard JSON request body but retains the legacy single-application configuration model.

The following rules apply:

Each webhook applies to one application.

The application must be specified using the x-app-id request header.

app_id cannot be specified in the request body.

The application scope cannot be changed after creation.

Only one enabled webhook can be configured for the same merchant and application.

Create a webhook

Delivery request format

Version 2026-04 uses application/json.

{
  "id": "evt_123",
  "name": "payment_intent.succeeded",
  "data": {
    "id": "pi_123",
    "object": "payment_intent",
    "status": "succeeded"
  }
}

Read the request body directly as a JSON object.

When verifying the signature, use the raw HTTP request body before parsing, formatting, or modifying the JSON.

Update rules

You can update fields such as:

url;

events;

description;

metadata; and

status.

The application scope cannot be changed while the webhook remains on version 2026-04.

Do not include app_id in the request body.

Version 2026-04 cannot be changed directly to 2024-10-10. To upgrade, use version 2026-09.

API version 2024-10-10

Configuration model

Version 2024-10-10 uses the legacy single-application configuration model.

The following rules apply:

Each webhook applies to one application.

The application must be specified using the x-app-id request header.

app_id cannot be specified in the request body.

The application scope cannot be changed after creation.

Only one enabled webhook can be configured for the same merchant and application.

Create a webhook

Provide the application ID in the x-app-id header:

If api_version is omitted when creating a webhook, UseePay uses 2024-10-10.

To avoid relying on the default version, explicitly provide api_version.

Delivery request format

Version 2024-10-10 uses application/x-www-form-urlencoded.

The data form field contains a JSON string.

Your endpoint must:

Read the data form field.

URL-decode the field value.

Parse the decoded value as JSON.

Update rules

You can update fields such as:

url;

events;

description;

metadata; and

status.

The application scope cannot be changed while the webhook remains on version 2024-10-10.

Do not include app_id in the request body.

Version 2024-10-10 cannot be changed directly to 2026-04. To upgrade, use version 2026-09.

Upgrade to API version 2026-09

An existing 2024-10-10 or 2026-04 webhook can be upgraded to 2026-09.

Retain the existing application scope

Explicitly set api_version:

{
  "api_version": "2026-09"
}

The existing application scope is retained when app_id is omitted.

Change the scope during the upgrade

Include app_id in the same request:

{
  "api_version": "2026-09",
  "app_id": "store-a.example.com,store-b.example.com"
}

To upgrade directly to merchant-level scope:

{
  "api_version": "2026-09",
  "app_id": "*"
}

Upgrade restrictions

The following rules apply:

Updating other fields without api_version does not automatically upgrade a legacy webhook.

A legacy webhook cannot switch directly between 2024-10-10 and 2026-04.

After a webhook is upgraded to 2026-09, it cannot be downgraded.

Before upgrading from 2024-10-10, update the endpoint to accept application/json.

All scope and endpoint limits are validated during the upgrade.

Use events to specify the event types delivered to the endpoint.

{
  "events": [
    "payment_intent.succeeded",
    "payment_intent.payment_failed"
  ]
}

Use ["*"] by itself to subscribe to all supported webhook events:

{
  "events": ["*"]
}

Do not combine * with another event type.

For the complete event list, see Supported Webhook Events.

Signature verification

UseePay includes an RSA signature in the sign request header.

The verification input depends on the API version:

API version	Verification input
`2026-09`	Raw JSON request body
`2026-04`	Raw JSON request body
`2024-10-10`	Legacy form-encoded webhook data

For JSON webhook versions, verify the signature against the raw HTTP request body before:

parsing the JSON;

formatting or serializing the JSON again;

changing whitespace;

extracting individual fields; or

modifying character encoding.

For detailed instructions, see Webhook Activation/Signature Verification Steps.

Respond quickly

Return an HTTP 2xx status code as soon as the event is received.

Process time-consuming business logic asynchronously to avoid delivery timeouts.

Example for JSON webhook versions:

Idempotency

The same event may be delivered more than once because of:

delivery retries;

network timeouts;

multiple webhook configurations pointing to the same URL; or

multiple matching scopes in version 2026-09.

Use event.id as the idempotency key.

Do not use only the business object ID as the idempotency key. The same business object may generate different event types at different times.

Event ordering

Do not rely on webhook events being delivered in the same order in which business changes occurred.

When strict ordering or state reconciliation is required, retrieve the latest state of the business object from the corresponding UseePay API.

Retry mechanism

If your webhook endpoint returns a non-2xx status code or times out, UseePay automatically retries the delivery using the following intervals:

1st retry: after 1 second

2nd retry: after 5 seconds

3rd retry: after 10 seconds

4th retry: after 30 seconds

5th retry: after 1 minute

Subsequent retries: 2 minutes, 3 minutes, 4 minutes, up to 2 hours

A delivery can be retried up to 18 times.

The same Event ID is used for retry deliveries.

Your endpoint should:

return 2xx quickly;

implement idempotency;

tolerate duplicate delivery;

tolerate out-of-order delivery; and

log the Event ID for troubleshooting.

Test your integration

To test webhooks:

Use UseePay Test Cards to create test payments.

View webhook delivery records in the Merchant Dashboard.

Confirm that the expected event types are delivered.

Confirm that signature verification succeeds.

Confirm that duplicate events are processed only once.

For version 2026-09, verify every configured application-level and merchant-level endpoint.

Supported Webhook Events

Webhook Activation/Signature Verification Steps

Unable to Receive Webhook Notifications

Technical support

For questions, contact support@useepay.com.

Overview#

Choose an API version#

Common integration process#

Webhook event structure#

API version 2026-09#

Configuration model#

Webhook scopes#

Single-application scope#

Multiple-application scope#

Merchant-level scope#

Specify the scope when creating a webhook#

Use the x-app-id header#

Use app_id in the request body#

app_id rules#

Create a single-application webhook#

Create a multiple-application webhook#

Create a merchant-level webhook#

Endpoint limits#

Event matching and delivery#

Event ID across multiple endpoints#

Delivery request format#

Update the webhook scope#

API version 2026-04#

Configuration model#

Create a webhook#

Delivery request format#

Update rules#

API version 2024-10-10#

Configuration model#

Create a webhook#

Delivery request format#

Update rules#

Upgrade to API version 2026-09#

Retain the existing application scope#

Change the scope during the upgrade#

Upgrade restrictions#

Subscribe to events#

Signature verification#

Respond quickly#

Idempotency#

Event ordering#

Retry mechanism#

Test your integration#

Related documentation#

Technical support#

Overview

Choose an API version

Common integration process

Webhook event structure

API version 2026-09

Configuration model

Webhook scopes

Single-application scope

Multiple-application scope

Merchant-level scope

Specify the scope when creating a webhook

Use the `x-app-id` header

Use `app_id` in the request body

`app_id` rules

Create a single-application webhook

Create a multiple-application webhook

Create a merchant-level webhook

Endpoint limits

Event matching and delivery

Event ID across multiple endpoints

Delivery request format

Update the webhook scope

API version 2026-04

Configuration model

Create a webhook

Delivery request format

Update rules

API version 2024-10-10

Configuration model

Create a webhook

Delivery request format

Update rules

Upgrade to API version 2026-09

Retain the existing application scope

Change the scope during the upgrade

Upgrade restrictions

Subscribe to events

Signature verification

Respond quickly

Idempotency

Event ordering

Retry mechanism

Test your integration

Related documentation

Technical support