Payment Webhook System

1. Event Types

payment.succeeded
payment.failed
payment.refunded

Events are delivered via HTTPS POST to a customer-configured endpoint.

2. Event Envelope

{
  "id": "evt_01HTY8Z3N7Y6WQ2WQ4T91P7R5A",
  "type": "payment.succeeded",
  "timestamp": "2025-03-08T14:52:31.482Z",
  "version": "2025-01-01",
  "data": {
    "payment_id": "pay_01HTY8XJ0DQK8TQ3W6A8KJX9P2",
    "amount": 4999,
    "currency": "USD",
    "status": "succeeded",
    "customer_id": "cus_12345",
    "order_id": "order_98765"
  }
}

Field definitions

Field	Type	Description
`id`	string	Globally unique, immutable event ID
`type`	string	Event type
`timestamp`	string	UTC ISO 8601 creation timestamp
`version`	string	Schema version used for this delivery
`data`	object	Event-specific payload

Amounts should use integer minor units, such as cents, to avoid floating-point ambiguity.

Example payloads

`payment.failed`

{
  "id": "evt_01HTY91MQ0QGRDF17C1ZNH28M4",
  "type": "payment.failed",
  "timestamp": "2025-03-08T14:55:04.112Z",
  "version": "2025-01-01",
  "data": {
    "payment_id": "pay_01HTY90A0HTW7EZ0B1WVDQZ66K",
    "amount": 4999,
    "currency": "USD",
    "status": "failed",
    "customer_id": "cus_12345",
    "order_id": "order_98765",
    "failure_code": "card_declined",
    "failure_message": "The card was declined."
  }
}

`payment.refunded`

{
  "id": "evt_01HTY95WXGXQQAF4NJVE0B2KX7",
  "type": "payment.refunded",
  "timestamp": "2025-03-08T15:02:18.940Z",
  "version": "2025-01-01",
  "data": {
    "payment_id": "pay_01HTY8XJ0DQK8TQ3W6A8KJX9P2",
    "refund_id": "ref_01HTY95R2BEFQ3A7G5YFR5D47C",
    "amount": 4999,
    "currency": "USD",
    "status": "refunded",
    "customer_id": "cus_12345",
    "order_id": "order_98765",
    "reason": "requested_by_customer"
  }
}

A payment may have multiple partial refunds. Each refund produ

Use this Webhook designer The form opens filled with this sample's inputs; change anything.