Webhooks

Key points

• Verify HMAC-SHA256 using the raw request body and the endpoint signing secret before processing an event.
• Deduplicate by event ID and return a successful HTTP response quickly. Failed deliveries are retried; use the Events API to recover anything missed.
• payment.succeeded is the fulfillment signal. Browser redirects and unsigned requests must not trigger fulfillment.

Example

{
  "object": "event",
  "id": "evt_3f2a9c7e1b4d0568a2cf",
  "type": "payment.succeeded",
  "mode": "live",
  "created_at": "2026-09-21T08:31:12.114Z",
  "data": {
    "object": {
      "object": "order",
      "trade_no": "TRD_9F3A2C7E...",
      "out_trade_no": "ORD_20260921_0001",
      "amount": 2990,
      "fee": 135,
      "net_amount": 2855,
      "currency": "USD",
      "status": "paid",
      "payment_method": "card",
      "refundable_until": null,
      "metadata": { "customer_id": "cus_42" },
      "paid_at": "2026-09-21T08:31:10.882Z"
    }
  }
}