Webhook Events Documentation

Webhook Request Format

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

Request Example

Webhook Data Structure

The data parameter in the webhook is a JSON string containing the following fields:

Field	Type	Description
`id`	string	Event ID, unique identifier starting with `evt_`
`name`	string	Event name, format: `object.event_type`
`data`	object	Business object data (PaymentIntent/Subscription/Invoice/Refund/CheckoutSession, etc.)

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 verify the authenticity of the request. See Webhook Activation/Signature Verification Steps for details.

2. Respond Quickly

Your webhook endpoint should quickly return a 2xx status code to avoid timeouts. Process time-consuming business logic asynchronously.

3. Idempotency Handling

The same event may be sent multiple times. Use event.id to implement idempotency.

4. Parse the data Parameter

The data parameter in the webhook request is a URL-encoded JSON string that needs to be decoded and parsed:

Retry Mechanism

If your webhook endpoint returns a non-2xx status code or times out, UseePay will automatically retry sending 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 like ngrok or webhook.site for local testing

Webhook Events

Webhook Activation/Signature Verification Steps

Technical Support

For questions, please contact: support@useepay.com

Webhook Request Format#

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. Parse the data Parameter#

Retry Mechanism#

FAQ#

Unable to Receive Webhook Notifications?#

How to Test Webhooks?#

Related Documentation#

Technical Support#