Platform
Webhook Events Catalog
Complete reference of every event PaymentHooks can send to your webhook endpoints, organised by category with sample payloads.
6 min read
Overview
PaymentHooks fires webhook events whenever significant actions occur in your account. Each event is delivered as an HTTP POST with a JSON body to every endpoint subscribed to that event type. Below is a complete catalog of all supported events grouped by domain.
Event envelope
Every webhook delivery wraps the resource inside a standard envelope. The top-level fields are consistent across all event types.
Event envelope structurejson
{
"id": "evt_1a2b3c4d5e6f",
"object": "event",
"api_version": "2026-04-22",
"created": 1751500800,
"type": "payment.succeeded",
"livemode": true,
"data": {
"object": {
"...": "resource object"
},
"previous_attributes": {
"...": "changed fields (only on *.updated events)"
}
},
"request": {
"id": null,
"idempotency_key": null
}
}| Field | Type | Description |
|---|---|---|
| id | string | Unique event identifier (ph_evt_ prefix). |
| type | string | Event type (e.g. payment.succeeded). |
| api_version | string | API version that generated the event. |
| created | integer | Unix timestamp when the event was created. |
| livemode | boolean | Whether the event occurred in live mode. |
| data.object | object | The full resource object at the time of the event. |
Payment events
| Event | Description |
|---|---|
| payment.created | A new payment is initiated. |
| payment.succeeded | Payment completes successfully. |
| payment.failed | Payment attempt fails. |
| payment.refunded | Payment is fully or partially refunded. |
| payment.disputed | Customer disputes the payment. |
| payment.requires_action | Payment requires additional customer action (e.g. 3DS). |
| payment_intent.created | A payment intent object is created. |
| payment_intent.succeeded | Payment intent succeeds. |
| payment_intent.payment_failed | Payment intent attempt fails. |
| payment_intent.requires_action | Payment intent requires customer action. |
| charge.refunded | A charge is refunded. |
| charge.dispute.created | A dispute is opened on a charge. |
| charge.dispute.closed | A dispute on a charge is closed. |
Sample payloadjson
{
"id": "ph_evt_9f3a1b2c4d5e",
"type": "payment.succeeded",
"created": 1751500800,
"data": {
"object": {
"id": "ph_pay_7k8m2n4p6q",
"amount": 9500,
"currency": "USD",
"status": "succeeded",
"customer": "ph_cus_3a5b7c9d1e",
"payment_method": "ph_pm_card_visa_4242",
"metadata": {}
}
}
}Invoice events
| Event | Description |
|---|---|
| invoice.created | Invoice is created. |
| invoice.finalized | Invoice is finalized and ready for payment. |
| invoice.paid | Invoice is fully paid. |
| invoice.payment_succeeded | Invoice payment succeeds. |
| invoice.payment_failed | Invoice payment attempt fails. |
| invoice.payment_reminder | Automated payment reminder sent. |
| invoice.overdue | Invoice is past its due date. |
| invoice.voided | Invoice is voided. |
| invoice.reminder | Manual or scheduled reminder sent for invoice. |
Sample payloadjson
{
"id": "ph_evt_a2b4c6d8e0f1",
"type": "invoice.paid",
"created": 1751500800,
"data": {
"object": {
"id": "ph_inv_5r7t9u1w3x",
"amount_due": 24900,
"amount_paid": 24900,
"currency": "USD",
"status": "paid",
"customer": "ph_cus_3a5b7c9d1e",
"subscription": "ph_sub_2d4f6h8j0l"
}
}
}Subscription events
| Event | Description |
|---|---|
| subscription.created | New subscription is created. |
| subscription.updated | Subscription details are updated. |
| subscription.cancelled | Subscription is cancelled. |
| subscription.renewed | Subscription renews successfully. |
| subscription.renewal_due | Subscription renewal is upcoming. |
| subscription.renewal_failed | Subscription renewal payment fails. |
| subscription.trial_will_end | Subscription trial period ends soon. |
| subscription.paused | Subscription is paused. |
| subscription.resumed | Paused subscription resumes. |
| subscription.deleted | Subscription is permanently deleted. |
| customer.subscription.created | Customer-scoped subscription created. |
| customer.subscription.updated | Customer-scoped subscription updated. |
| customer.subscription.deleted | Customer-scoped subscription deleted. |
| customer.subscription.paused | Customer-scoped subscription paused. |
| customer.subscription.resumed | Customer-scoped subscription resumed. |
Sample payloadjson
{
"id": "ph_evt_c3d5e7f9a1b2",
"type": "subscription.renewed",
"created": 1751500800,
"data": {
"object": {
"id": "ph_sub_2d4f6h8j0l",
"status": "active",
"customer": "ph_cus_3a5b7c9d1e",
"plan": "ph_plan_pro_monthly",
"current_period_start": 1751500800,
"current_period_end": 1754179200,
"cancel_at_period_end": false
}
}
}Customer events
| Event | Description |
|---|---|
| customer.created | New customer record is created. |
| customer.updated | Customer details are updated. |
| customer.deleted | Customer record is deleted. |
Sample payloadjson
{
"id": "ph_evt_d4e6f8a0b2c3",
"type": "customer.created",
"created": 1751500800,
"data": {
"object": {
"id": "ph_cus_3a5b7c9d1e",
"email": "[email protected]",
"name": "Jane Doe",
"created": 1751500800,
"metadata": {}
}
}
}Product events
| Event | Description |
|---|---|
| product.created | New product is created. |
| product.updated | Product details are updated. |
| product.deleted | Product is deleted. |
Sample payloadjson
{
"id": "ph_evt_e5f7a9b1c3d4",
"type": "product.created",
"created": 1751500800,
"data": {
"object": {
"id": "ph_prod_8m0n2p4r6s",
"name": "Enterprise Plan",
"active": true,
"description": "Full-featured enterprise subscription",
"metadata": {}
}
}
}Price events
| Event | Description |
|---|---|
| price.created | New price is created for a product. |
| price.updated | Price details are updated. |
| price.deleted | Price is deleted. |
Sample payloadjson
{
"id": "ph_evt_f6a8b0c2d4e5",
"type": "price.created",
"created": 1751500800,
"data": {
"object": {
"id": "ph_price_4t6u8v0w2x",
"product": "ph_prod_8m0n2p4r6s",
"unit_amount": 4900,
"currency": "USD",
"recurring": {
"interval": "month",
"interval_count": 1
},
"active": true
}
}
}Dispute events
| Event | Description |
|---|---|
| dispute.created | A dispute is opened. |
| dispute.updated | Dispute details are updated. |
| dispute.evidence_submitted | Evidence is submitted for a dispute. |
| dispute.won | Dispute is resolved in your favour. |
| dispute.lost | Dispute is resolved against you. |
| dispute.closed | Dispute is closed. |
Sample payloadjson
{
"id": "ph_evt_a7b9c1d3e5f6",
"type": "dispute.created",
"created": 1751500800,
"data": {
"object": {
"id": "ph_disp_1y3a5b7c9d",
"payment": "ph_pay_7k8m2n4p6q",
"amount": 9500,
"currency": "USD",
"status": "needs_response",
"reason": "fraudulent",
"evidence_due_by": 1752710400
}
}
}Checkout Session events
| Event | Description |
|---|---|
| checkout.session.created | Checkout session is created. |
| checkout.session.completed | Checkout session completes successfully. |
| checkout.session.async_payment_succeeded | Async payment on checkout session succeeds. |
| checkout.session.async_payment_failed | Async payment on checkout session fails. |
| checkout.session.payment_failed | Checkout session payment fails. |
| checkout.session.expired | Checkout session expires before completion. |
| checkout_session.created | Legacy checkout session created event. |
Sample payloadjson
{
"id": "ph_evt_b8c0d2e4f6a7",
"type": "checkout.session.completed",
"created": 1751500800,
"data": {
"object": {
"id": "ph_cs_6e8f0a2b4c",
"payment_status": "paid",
"amount_total": 9500,
"currency": "USD",
"customer": "ph_cus_3a5b7c9d1e",
"mode": "payment",
"success_url": "https://example.com/success"
}
}
}Payment Link events
| Event | Description |
|---|---|
| payment_link.created | Payment link is created. |
| payment_link.updated | Payment link is updated. |
Sample payloadjson
{
"id": "ph_evt_c9d1e3f5a7b8",
"type": "payment_link.created",
"created": 1751500800,
"data": {
"object": {
"id": "ph_plink_3g5h7i9j1k",
"url": "https://pay.paymenthooks.com/pl/ph_plink_3g5h7i9j1k",
"active": true,
"amount": 2500,
"currency": "USD"
}
}
}Gateway events
| Event | Description |
|---|---|
| gateway.connected | A payment gateway is connected. |
| gateway.disconnected | A payment gateway is disconnected. |
| gateway.health_changed | Gateway health status changes. |
Sample payloadjson
{
"id": "ph_evt_d0e2f4a6b8c9",
"type": "gateway.connected",
"created": 1751500800,
"data": {
"object": {
"id": "ph_gw_2l4m6n8o0p",
"provider": "stripe",
"status": "connected",
"supported_currencies": [
"USD",
"EUR",
"GBP"
],
"connected_at": 1751500800
}
}
}