Subscription webhook events

Subscription webhooks are emitted from confirmed on-chain events. They use the same signing headers and retry behavior as order webhooks, but have their own envelope.

Envelope

{
  "id": "84532:0xabc...:3",
  "type": "subscription.payment_succeeded",
  "occurredAt": "2026-08-05T10:15:30.000Z",
  "subscriptionId": "0x1234...",
  "chainId": 84532,
  "transactionHash": "0xabc...",
  "subscription": {
    "payerAddress": "0xpayer...",
    "status": "active",
    "paidCycles": 1,
    "totalPaid": "1000000",
    "nextCycleStart": "2026-09-05T10:15:30.000Z"
  },
  "product": { "id": "product_...", "name": "Pro monthly" },
  "plan": { "id": "3", "intervalSeconds": 2592000, "amountPerCycle": "1000000" },
  "token": { "address": "0xtoken...", "symbol": "USDC", "decimals": 6 },
  "payment": { "cycleIndex": 0, "grossAmount": "1000000", "merchantAmount": "990000", "feeAmount": "10000" },
  "data": {}
}

Field	Meaning
`id`	Stable delivery ID in the form `chainId:transactionHash:logIndex`. Deduplicate with this value.
`type`	Subscription lifecycle event type.
`occurredAt`	Timestamp of the block containing the event.
`subscriptionId`	On-chain `bytes32` subscription ID.
`chainId`	EVM chain ID where the event occurred.
`transactionHash`	Transaction that emitted the event.
`subscription`	Current subscription snapshot, including payer, status, authorization end, paid cycles, total paid, and next collection time.
`product`	Merchant product ID, name, and description when the plan is linked to a SixPay product.
`plan`	On-chain plan ID, billing interval, duration limit, and configured amount per cycle.
`token`	Token address, symbol, name when known, and decimals.
`payment`	Normalized current-payment amount and cycle details. Amounts remain atomic-unit strings.
`data`	Decoded chain event fields. Treat it as event-specific data.

Event types

Event	Trigger	Merchant action
`subscription.created`	A customer creates an on-chain subscription.	Create or update the merchant subscription record. Do not treat this alone as a paid billing-period receipt.
`subscription.payment_succeeded`	A confirmed `SubscriptionPaymentExecuted` collection.	Deduplicate by `id`, then grant or extend the relevant entitlement.
`subscription.failed`	A confirmed `SubscriptionFailed` event.	Stop paid access or enter your dunning flow; inspect `data.reasonHash`.
`subscription.cancelled`	A customer cancellation is confirmed.	Stop future renewals under your cancellation policy.
`subscription.expired`	The contract finalizes an expired authorization or plan.	End service or request a new authorization.

Payment-success data

For subscription.payment_succeeded, use payment.grossAmount with token.symbol and token.decimals for the amount paid. The raw fields emitted by SubscriptionPaymentExecuted remain in data:

{
  "subscriptionId": "0x1234...",
  "cycleIndex": "1",
  "executor": "0xkeeper...",
  "grossAmount": "1000000",
  "merchantAmount": "990000",
  "feeAmount": "10000",
  "nextCycleStart": "1785945600"
}

Amounts are token atomic units, not display decimals. Resolve token decimals from the plan configuration before presenting them to users. executor may be a Keeper address; it is not necessarily the payer.

Failure and lifecycle data

subscription.failed includes subscriptionId, cycleIndex, and reasonHash. The cancellation and expiry events include subscriptionId. Preserve the full raw payload for reconciliation because delivery order between distinct confirmed transactions is not a substitute for your own entitlement idempotency.

Retry behavior

SixPay retries non-2xx, network, and timeout failures. The same event may be delivered more than once, while a different event can refer to the same subscription. Return a 2xx response only after durable handling, or persist the event before queuing asynchronous work.

Overview

Get started

Build checkout

Operate

Reference

Subscription webhook events

Envelope

Event types

Payment-success data

Failure and lifecycle data

Retry behavior

​Envelope

​Event types

​Payment-success data

​Failure and lifecycle data

​Retry behavior

Envelope

Event types

Payment-success data

Failure and lifecycle data

Retry behavior