Webhook Events Documentation

Overview

UseePay sends webhook event notifications to your configured server when specific business events occur (such as successful payments, subscription creation, etc.). All webhook notifications use a unified JSON data format and are pushed to your configured webhook URL via HTTP POST requests.

Through webhooks, you can receive real-time notifications of payment status changes, subscription updates, and other important business events without the need for active polling, improving system integration efficiency.

Webhook Message Format

HTTP Request Format

UseePay sends webhooks as HTTP POST requests with form-data format:

POST /your-webhook-endpoint 
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded

data={...business object JSON...}

Webhook Data Structure

The data parameter contains a JSON string with the business object data. The structure varies depending on the event type:

For Payment Intent Events:

{
  "id": "pi_1234567890",
  "object": "payment_intent",
  "amount": 10000,
  "currency": "USD",
  "status": "succeeded",
  "customer_id": "cus_abc123",
  "payment_method": {...},
  "created_at": "2024-01-27T10:30:00Z",
  "metadata": {}
}

For Subscription Events:

{
  "id": "sub_9876543210",
  "object": "subscription",
  "status": "active",
  "customer_id": "cus_abc123",
  "current_period_start": "2024-01-27T00:00:00Z",
  "current_period_end": "2024-02-27T00:00:00Z",
  "recurring": {...},
  "created_at": "2024-01-27T10:30:00Z"
}

For Invoice Events:

{
  "id": "inv_1122334455",
  "object": "invoice",
  "status": "paid",
  "customer_id": "cus_abc123",
  "subscription_id": "sub_9876543210",
  "total_amount": 9900,
  "currency": "USD",
  "created_at": "2024-01-27T10:30:00Z"
}

Common Fields

All business objects contain these common fields:

Field	Type	Description
`id`	String	Unique identifier for the object
`object`	String	Object type (e.g., "payment_intent", "subscription", "invoice")
`status`	String	Current status of the object
`created_at`	String	Creation timestamp in ISO 8601 format

Delivery Mechanism

Asynchronous Delivery: Events are sent asynchronously without blocking your business operations

Retry Logic: Failed deliveries will be automatically retried

Guaranteed Delivery: We ensure reliable delivery of all webhook events

Supported Webhook Event Types

1. Payment Intent Events

Event Name	Trigger Condition	Description
`payment_intent.created`	When a payment intent is created	A payment intent has been created.
`payment_intent.requires_payment_method`	When payment method is required	This payment intent requires payment method to proceed.
`payment_intent.requires_capture`	When merchant capture is required	Merchant capture is required to fulfill this payment intent.
`payment_intent.requires_customer_action`	When customer action is needed	Additional customer action is required to fulfill this payment intent.
`payment_intent.pending`	When payment is processing	The payment request has been accepted. Waiting for the final result.
`payment_intent.succeeded`	When payment succeeds	A payment intent has been fulfilled.
`payment_intent.cancelled`	When payment is cancelled	The payment intent has been cancelled.
`payment_intent.failed`	When payment fails	The payment intent has been failed.

Data Object Type: PaymentIntent

2. Subscription Events

Event Name	Trigger Condition	Description
`subscription.created`	When subscription is created (incomplete status)	A subscription has been created.
`subscription.active`	When subscription becomes active	This subscription is active.
`subscription.updated`	When subscription is updated	The subscription has been changed, such as status update, trial start & end, cancel at period end, etc.
`subscription.unpaid`	When subscription is unpaid	This subscription is unpaid.
`subscription.paused`	When subscription is paused	This subscription has paused.
`subscription.cancelled`	When subscription is cancelled	The subscription has been cancelled.
`subscription.expired`	When subscription expires	This subscription has expired.

Data Object Type: Subscription

3. Invoice Events

Event Name	Trigger Condition	Description
`invoice.sent`	When invoice is created (open status)	The invoice is ready to be paid.
`invoice.paid`	When invoice payment succeeds	The invoice has been paid successfully.
`invoice.payment_failed`	When invoice payment fails	The invoice is marked as PAYMENT_FAILED and should be treated as bad debt in the accounting process.
`invoice.cancelled`	When invoice is cancelled	The invoice is cancelled.

Data Object Type: Invoice

4. Refund Events

Event Name	Trigger Condition	Description
`refund.received`	When refund request is received	This refund request has been received and will be processed later.
`refund.accepted`	When refund request is accepted	This refund request has been accepted and started processing. Please note, the final fund settlement time will depend on the bank or the payment method's processing time.
`refund.succeeded`	When refund succeeds	This refund has been fulfilled successfully.
`refund.failed`	When refund fails	This refund has failed.

Data Object Type: Refund

5. Checkout Session Events

Event Name	Trigger Condition	Description
`checkout_session.completed`	When checkout session completes	A checkout session has been completed successfully.
`checkout_session.expired`	When checkout session expires	A checkout session has expired without being completed.

Event Trigger 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 Signatures

You should verify the signature of webhook requests to ensure they originate from UseePay.

2. Idempotency Handling

The same event may be sent multiple times. Use event.id for idempotency handling.

3. Quick Response

Your webhook endpoint should respond quickly with HTTP 200 to avoid timeouts. Process business logic asynchronously.

4. Error Handling

When you return a non-2xx status code, UseePay will retry the webhook delivery.

5. Security Considerations

Use HTTPS for your webhook URL

Validate the webhook signature

Implement rate limiting

Log all webhook events for debugging

Examples

How to Receive Webhooks

HTTP Request Example:

POST /webhook HTTP/1.1
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded

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":{}}

Parsing Example (Node.js/Express):

Parsing Example (Python/Flask):

Parsing Example (Java/Spring Boot):

Payment Intent Success Event

Webhook Data (PaymentIntent object):

{
  "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": {}
}

Subscription Active Event

Webhook Data (Subscription object):

{
  "id": "sub_9876543210",
  "object": "subscription",
  "status": "active",
  "customer_id": "cus_abc123",
  "current_period_start": "2024-01-27T00:00:00Z",
  "current_period_end": "2024-02-27T00:00:00Z",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "unit_amount": 9900
  },
  "created_at": "2024-01-27T10:30:00Z",
  "metadata": {}
}

Invoice Paid Event

Webhook Data (Invoice object):

{
  "id": "inv_1122334455",
  "object": "invoice",
  "status": "paid",
  "customer_id": "cus_abc123",
  "subscription_id": "sub_9876543210",
  "total_amount": 9900,
  "currency": "USD",
  "period_start": "2024-01-27T00:00:00Z",
  "period_end": "2024-02-27T00:00:00Z",
  "payment_intent_id": "pi_1234567890",
  "created_at": "2024-01-27T10:30:00Z",
  "metadata": {}
}

Checkout Session Completed Event

Webhook Data (CheckoutSession object):

{
  "id": "cs_6677889900",
  "object": "checkout.session",
  "mode": "subscription",
  "status": "complete",
  "payment_status": "paid",
  "customer_id": "cus_abc123",
  "subscription_id": "sub_9876543210",
  "payment_intent_id": "pi_1234567890",
  "amount": 9900,
  "currency": "USD",
  "created_at": "2024-01-27T10:30:00Z",
  "metadata": {}
}

Testing Webhooks

Test Mode

UseePay provides a test mode where you can trigger webhook events without processing real payments.

Webhook Logs

You can view webhook delivery logs in your UseePay dashboard, including:

Event type

Delivery status

Response code

Retry attempts

Timestamp

Troubleshooting

Common Issues

Q1: Why am I not receiving webhooks?

Possible reasons:

Webhook URL not configured

Webhook URL is not accessible

Firewall blocking incoming requests

SSL certificate issues (if using HTTPS)

Solutions:

Verify your webhook URL configuration

Test your endpoint with tools like curl or Postman

Check firewall settings

Ensure valid SSL certificate

Q2: How to handle duplicate events?

Use the event.id field for idempotency. Store processed event IDs and skip events that have already been processed.

Q3: What happens if my webhook endpoint is down?

UseePay will retry failed webhook deliveries according to the retry schedule. You can view failed deliveries in your dashboard.

Q4: How long does UseePay retry failed webhooks?

Webhooks are retried with exponential backoff for up to 3 days.

Event Summary Table

Category	Event Count	Events
Payment Intent	8	created, requires_payment_method, requires_capture, requires_customer_action, pending, succeeded, cancelled, failed
Subscription	7	created, active, updated, unpaid, paused, cancelled, expired
Invoice	4	sent, paid, payment_failed, cancelled
Refund	4	received, accepted, succeeded, failed
Checkout Session	2	completed, expired
Payment Method	2	created, updated
Total	27

Support

If you have questions about webhooks or need assistance with integration:

Email: support@useepay.com

Webhook Events Documentation (testing)

Webhook Events Documentation#

Overview#

Webhook Message Format#

HTTP Request Format#

Webhook Data Structure#

Common Fields#

Delivery Mechanism#

Supported Webhook Event Types#

1. Payment Intent Events#

2. Subscription Events#

3. Invoice Events#

4. Refund Events#

5. Checkout Session Events#

Event Trigger Flow#

Best Practices for Receiving Webhooks#

1. Verify Signatures#

2. Idempotency Handling#

3. Quick Response#

4. Error Handling#

5. Security Considerations#

Examples#

How to Receive Webhooks#

Payment Intent Success Event#

Subscription Active Event#

Invoice Paid Event#

Checkout Session Completed Event#

Testing Webhooks#

Test Mode#

Webhook Logs#

Troubleshooting#

Common Issues#

Event Summary Table#

Support#