Overview

UseePay sends event notifications to your configured webhook URL via HTTP POST requests.

For a better integration experience, we recommend using webhook version 2026-04 whenever possible.

For more information about supported versions, see: https://docs-v2.useepay.com/8649675m0.

Request Format

UseePay sends webhook events using application/json.

Your webhook endpoint should accept a standard JSON request body.

Content-Type

Request Example

Webhook Data Structure

The webhook request body is a JSON object containing the following fields:

Field	Type	Description
`id`	string	Event ID, a unique identifier starting with `evt_`
`name`	string	Event name, in the format `object.event_type`
`data`	object	Business object data, such as PaymentIntent, Subscription, Invoice, Refund, CheckoutSession, Dispute, etc.

Event Types

For the full list of supported webhook event types, see:

Event Types

Complete Example

{
  "id": "evt_79bdd43e4d0f464694fa433a5d467980",
  "name": "payment_intent.succeeded",
  "data": {
    "id": "pi_1234567890",
    "object": "payment_intent",
    "amount": 10000,
    "currency": "USD",
    "status": "succeeded",
    "customer_id": "cus_abc123",
    "payment_method": {
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242"
      }
    },
    "created_at": "2024-01-27T10:30:00Z",
    "metadata": {}
  }
}

Event Processing Flow

Business Event Occurs
    ↓
UseePay System Detects Status Change
    ↓
Webhook Event Generated
    ↓
HTTP POST to Your Webhook URL
    ↓
Your Server Processes Event

Best Practices for Receiving Webhooks

1. Verify Signature

UseePay includes signature information in the request headers to help you verify the authenticity of the request.

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

See Webhook Activation/Signature Verification Steps for details.

2. Respond Quickly

Your webhook endpoint should return a 2xx HTTP status code as soon as the event is received.

Time-consuming business logic should be processed asynchronously to avoid webhook delivery timeouts.

3. Idempotency Handling

The same event may be sent multiple times. Use event.id to implement idempotency and avoid duplicate processing.

4. Read the JSON Request Body

The webhook request body is a standard JSON object.

You can directly read id, name, and data from the request body.

Node.js Example

Python Example

Java Example

Important Notes

Ensure your server supports JSON request parsing.

Always return HTTP 2xx as soon as the event is received.

Webhook events may be retried if they are not acknowledged.

Use event.id for idempotency handling.

Use the raw HTTP request body when verifying the webhook signature.

Retry Mechanism

If your webhook endpoint returns a non-2xx status code or times out, UseePay will automatically retry sending the webhook with 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

Maximum of 18 retries.

FAQ

Unable to Receive Webhook Notifications?

Please refer to the Unable to Receive Webhook Notifications troubleshooting guide.

How to Test Webhooks?

Use UseePay Test Cards to create test payments.

View webhook sending logs in the Merchant Dashboard.

Use tools such as ngrok or webhook.site for local testing.

Webhook Events

Webhook Activation/Signature Verification Steps

Technical Support

For questions, please contact: support@useepay.com

Webhook Integration Guide(version 2026-04)

Overview#

Request Format#

Content-Type#

Request Example#

Webhook Data Structure#

Event Types#

Complete Example#

Event Processing Flow#

Best Practices for Receiving Webhooks#

1. Verify Signature#

2. Respond Quickly#

3. Idempotency Handling#

4. Read the JSON Request Body#

Node.js Example#

Python Example#

Java Example#

Important Notes#

Retry Mechanism#

FAQ#

Unable to Receive Webhook Notifications?#

How to Test Webhooks?#

Related Documentation#

Technical Support#

Overview

Request Format

Content-Type

Request Example

Webhook Data Structure

Event Types

Complete Example

Event Processing Flow

Best Practices for Receiving Webhooks

1. Verify Signature

2. Respond Quickly

3. Idempotency Handling

4. Read the JSON Request Body

Node.js Example

Python Example

Java Example

Important Notes

Retry Mechanism

FAQ

Unable to Receive Webhook Notifications?

How to Test Webhooks?

Related Documentation

Technical Support