Events
Webhook Events
Complete reference for all webhook event types and their payloads
All Event Types
Subscribe to the events your integration needs
| Event | Category | Description |
|---|---|---|
payment.succeeded | payment | Sent when a payment completes successfully. Use this to fulfill orders and update your records. |
payment.failed | payment | Sent when a payment fails. Contains error details to help diagnose the issue. |
payment.processing | payment | Sent when a payment is being processed. Common for bank transfers and delayed payment methods. |
refund.created | refund | Sent when a refund request is initiated. The refund may still be processing. |
refund.completed | refund | Sent when a refund is successfully processed and funds are returned to the customer. |
refund.failed | refund | Sent when a refund cannot be completed. Contains failure reason. |
dispute.created | dispute | Sent when a chargeback or dispute is filed against a transaction. Action required. |
test.webhook | test | Test event for verifying your webhook endpoint connectivity and signature verification. |
Webhook Headers
Every webhook request includes these headers
| Header | Description | Example |
|---|---|---|
X-Webhook-Signature | HMAC-SHA256 signature for verification | sha256=abc123... |
X-Webhook-Timestamp | Unix timestamp when the webhook was sent (for replay protection) | 1705394395 |
X-Webhook-Event-Id | Unique event identifier (same as payload id) | evt_01HQKZ7N3B... |
X-Webhook-Event-Type | Event type for quick routing without parsing body | payment.succeeded |
Content-Type | Content type of the request body | application/json |
Use X-Webhook-Event-Id for idempotent processing and X-Webhook-Timestamp for replay attack protection.
Standard Payload Structure
All webhook payloads follow the same wrapper format
API Version: 2024-01-01
JSON
Webhook Payload Structure{
"id": "evt_01HQKZ7N3BXYZ...",
"object": "event",
"type": "payment.succeeded",
"created": "2025-01-16T08:19:55Z",
"livemode": false,
"api_key_id": "client_01HQKZ...",
"data": {
"object": {
"id": "txn_01HQKZ...",
"object": "transaction",
"amount": 10000,
"currency": "USD",
"status": "SUCCESS",
"merchant_ref": "ORDER-2025-001"
}
},
"api_version": "2024-01-01"
}Field Descriptions
| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier (use for idempotency) |
object | string | Always "event" |
type | string | Event type (e.g., "payment.succeeded") |
created | string | ISO 8601 timestamp when event was created |
livemode | boolean | true for production, false for sandbox |
api_key_id | string | ID of the API key that triggered the event |
data | object | Contains the resource object that triggered the event |
api_version | string | API version used (currently "2024-01-01") |
Payload Examples
Example payloads for each common event type
payment.succeeded
Most common
Sent when a payment completes successfully. Use this event to fulfill orders.
JSON
payment.succeeded{
"id": "evt_01HQKZ7N3BXYZ123456",
"object": "event",
"type": "payment.succeeded",
"created": "2025-01-16T08:19:55Z",
"livemode": true,
"api_key_id": "client_01HQKZ7N3B...",
"data": {
"object": {
"id": "txn_01HQKZ7N3BXYZ",
"object": "transaction",
"amount": 150000,
"currency": "USD",
"status": "SUCCESS",
"merchant_ref": "ORDER-2025-001234",
"description": "Premium subscription - Annual",
"customer_email": "[email protected]",
"payment_method": "card",
"card_brand": "visa",
"card_last4": "4242",
"created_at": "2025-01-16T08:19:00Z",
"completed_at": "2025-01-16T08:19:55Z",
"metadata": {
"plan_id": "premium_annual",
"user_id": "usr_123456"
}
}
},
"api_version": "2024-01-01"
}payment.failed
Important
Sent when a payment fails. Contains error details to help diagnose the issue.
JSON
payment.failed{
"id": "evt_01HQKZ7N3BXYZ789012",
"object": "event",
"type": "payment.failed",
"created": "2025-01-16T08:20:30Z",
"livemode": true,
"api_key_id": "client_01HQKZ7N3B...",
"data": {
"object": {
"id": "txn_01HQKZ7N3BXYZ",
"object": "transaction",
"amount": 50000,
"currency": "USD",
"status": "FAILED",
"merchant_ref": "ORDER-2025-005678",
"description": "Standard plan - Monthly",
"customer_email": "[email protected]",
"payment_method": "card",
"failure_code": "card_declined",
"failure_message": "Your card was declined",
"created_at": "2025-01-16T08:20:00Z",
"failed_at": "2025-01-16T08:20:30Z"
}
},
"api_version": "2024-01-01"
}refund.completed
Refund
Sent when a refund is successfully processed and funds are returned to the customer.
JSON
refund.completed{
"id": "evt_01HQKZ7N3BXYZ345678",
"object": "event",
"type": "refund.completed",
"created": "2025-01-17T10:30:00Z",
"livemode": true,
"api_key_id": "client_01HQKZ7N3B...",
"data": {
"object": {
"id": "rfd_01HQKZ7N3BXYZ",
"object": "refund",
"amount": 50000,
"currency": "USD",
"status": "COMPLETED",
"transaction_id": "txn_01HQKZ7N3BXYZ",
"merchant_ref": "REFUND-2025-001234",
"reason": "customer_request",
"description": "Customer requested refund",
"created_at": "2025-01-17T10:00:00Z",
"completed_at": "2025-01-17T10:30:00Z"
}
},
"api_version": "2024-01-01"
}dispute.created
Action needed
Sent when a chargeback is filed. You need to respond with evidence before the deadline.
JSON
dispute.created{
"id": "evt_01HQKZ7N3BXYZ901234",
"object": "event",
"type": "dispute.created",
"created": "2025-01-20T14:00:00Z",
"livemode": true,
"api_key_id": "client_01HQKZ7N3B...",
"data": {
"object": {
"id": "dsp_01HQKZ7N3BXYZ",
"object": "dispute",
"amount": 150000,
"currency": "USD",
"status": "NEEDS_RESPONSE",
"transaction_id": "txn_01HQKZ7N3BXYZ",
"reason": "fraudulent",
"evidence_due_by": "2025-02-03T23:59:59Z",
"created_at": "2025-01-20T14:00:00Z"
}
},
"api_version": "2024-01-01"
}Disputes have strict deadlines. Respond quickly with evidence to avoid automatic loss.
Best Practices
Idempotent Processing
Store processed event IDs and skip duplicate events to prevent double-processing.
Respond Quickly with 200
Return HTTP 200 within 30 seconds, then process the event asynchronously.
Don't Depend on Order
Webhooks may arrive out of order. Use timestamps to process in the correct sequence.