Webhooks - Waffo Pancake

Overview

Webhooks deliver real-time notifications to your server when events occur — orders, payments, subscriptions, and refunds.

Event occurs → Waffo Pancake → fan-out → Your channel(s)

A single store can have multiple webhooks, each delivering to a different channel. The available channels are:

Channel	Delivery target	Payload format
`http`	Your HTTPS endpoint	RSA-SHA256-signed JSON envelope
`feishu`	Lark / Feishu bot incoming webhook	Interactive card (Lark format)
`discord`	Discord channel webhook	Embed message (Discord format)
`telegram`	Telegram bot `sendMessage` URL	HTML-formatted text
`slack`	Slack incoming webhook	Attachment with mrkdwn fields

The http channel uses the JSON envelope and signature verification described on this page — most of this guide covers that channel. For the IM channels, payloads use each platform’s native format and authentication is handled by the URL token; you don’t need to verify signatures.

Using TypeScript? The @waffo/pancake-ts SDK has built-in public keys and auto-detects the environment — one line to verify the http channel.

Setup

Choose a channel and prepare its URL

HTTP — build a server endpoint that accepts POST requests and returns 200.
Feishu / Discord / Telegram / Slack — create a bot or incoming webhook in the target platform and copy its URL. For Telegram, also note the chat ID that should receive messages.

(HTTP only) Copy the verification public key

Waffo uses one fixed key pair per environment — Test and Production — shared across all stores. You don’t get a key back when registering a webhook; you read it from the Dashboard.Open the Dashboard → any store → Settings → Webhooks, and copy the Webhook Public Key for the environment you’re integrating (Test or Production). Store it in your server’s config; you’ll use it to verify every incoming HTTP webhook.

Every store’s Dashboard shows the same Test key and the same Production key — they’re platform-level. Adding, editing, or deleting webhook URLs does not change them.

Add a webhook in Dashboard → Settings → Webhooks, or call POST /v1/actions/store/add-webhook. Each webhook record specifies one channel, one URL, the subscribed events, and the target environment (testMode: true for Test, false for Production). You can register multiple webhooks per store.

Send a test event

Use the Dashboard “Send Test Event” button to deliver a sample event to one or all of your registered webhooks.

Verify and handle events

For the HTTP channel, use the code examples below to verify signatures before processing events. IM channels deliver pre-rendered messages and require no handling on your side.

Environment Isolation

Each webhook is registered for a single environment via the testMode flag. Test and Production are fully independent:

Aspect	Test	Production
Webhook record	`testMode: true`	`testMode: false`
Signing key (HTTP only)	Test key pair	Production key pair
Verification public key (HTTP only)	Dashboard Test key	Dashboard Production key
Selector when delivering	Header `X-Environment: test`	Header `X-Environment: prod` (or omitted)

The mode field in each HTTP payload indicates the source environment: "test" or "prod".

Always use the public key matching the event’s mode. A Test key cannot verify Production events, and vice versa.

Payload Format

Headers

Header	Description
`Content-Type`	`application/json`
`X-Waffo-Signature`	Signature string: `t=<timestamp>,v1=<signature>`
`X-Waffo-Event`	Event type (e.g., `order.completed`)

Body

{
  "id": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "order.completed",
  "eventId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "chargedAmount": "98.00",
    "amount": "98.00",
    "taxAmount": "8.00",
    "taxRate": 8,
    "taxName": "Consumption Tax",
    "subtotal": "100.00",
    "total": "108.00",
    "listPrice": {
      "total": "108.00",
      "subtotal": "100.00",
      "taxAmount": "8.00",
      "taxRate": 8,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "orderMetadata": { "planId": "pro" },
    "orderMerchantExternalId": "ORDER-2026-00891",
    "productMetadata": {},
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "paymentDate": "2026-03-10"
  }
}

Top-level Fields

Field	Type	Description
`id`	string	Event entity ID — same as `eventId` for most events
`timestamp`	string	Event time (ISO 8601 UTC)
`eventType`	string	Event type (see Event Types)
`eventId`	string	Business event identifier — maps to different entities per event type (see eventId Mapping)
`storeId`	string	Store ID
`storeName`	string	Store name
`mode`	string	`"test"` or `"prod"`

`data` Fields

The table below defines every data field — its type, when it appears, and what it means. For the exact field set of a given event, see the complete body under Event Details. In the Present column, “Payment events” means order.completed and subscription.payment_succeeded; “Subscription events” means every subscription.* event except subscription.payment_succeeded. That one event is a pure payment event: it describes a single charge and carries neither the subscription period nor its status.

Field	Type	Present	Description
`orderId`	string	Always	Order ID
`orderStatus`	string	All but `subscription.payment_succeeded`	`completed` for one-time orders; `active` / `canceling` / `canceled` / `past_due` for subscriptions
`buyerEmail`	string	Always	Customer email address
`currency`	string	Always	ISO 4217 currency code (e.g., `"USD"`, `"JPY"`)
`orderMetadata`	object	Always	Order-level metadata from the checkout session (merchant-defined key-value pairs)
`productMetadata`	object	Always	Product-level metadata set when creating or updating the product
`merchantProvidedBuyerIdentity`	string	When set at checkout	Merchant’s own customer identifier
`orderMerchantExternalId`	string	When set at checkout	Order’s business-side identifier (max 128 chars). Also present on `refund.*`, inherited from the original order
`refundTicketMerchantExternalId`	string	`refund.*`, when set	Refund ticket’s business-side identifier (max 128 chars)
`billingDetail`	object	When set at checkout	Billing address (`country`, `isBusiness`, …)
`chargedAmount`	string	Payment events, when the channel reported an amount	What this charge actually took, tax included (display format). Omitted — never zeroed — when the channel reported no amount
`refundedAmount`	string	`refund.*`, when the channel reported an amount	What this refund actually returned (display format). Omitted — never zeroed — when the channel reported no amount
`listPrice`	object	Payment events	The list price recorded when the order was placed: `total` / `subtotal` / `taxAmount` / `taxRate` / `taxName`. Differs from `chargedAmount` when a prorated credit or a zero-amount card check applies
`originalChargedAmount`	string	`refund.*`, when the channel reported an amount for that payment	What the payment being refunded actually collected (display format). This is the ceiling a refund can reach; `originalPayment.total` next to it is the list price, and the two differ when a prorated credit or a zero-amount card check applied to that payment. Omitted — never zeroed — when the channel reported no amount
`originalPayment`	object	`refund.*`	The payment being refunded, as originally charged: `total` / `subtotal` / `taxAmount` / `taxRate` / `taxName`. Its `taxAmount` is the original order’s real tax
`planPrice`	object	Subscription events	The subscription’s list price for the current phase: `total` / `subtotal` / `taxAmount` / `taxRate` / `taxName`
`amount`	string	Always	Deprecated — Amount for this event, tax included (display format). On payment events this is what was actually charged; on `refund.` it is the refund amount, not* the order amount. See Deprecated amount fields
`taxAmount`	string	Always	Deprecated — Tax amount (display format). Always `"0"` on `refund.*` — refunds carry no tax breakdown
`taxRate`	number	When tax applied	Deprecated — Tax rate as a percentage number (e.g., `10` for 10%)
`taxName`	string	When tax applied	Deprecated — Tax name (e.g., `"Consumption Tax"`)
`subtotal`	string	When available	Deprecated — Subtotal before tax (display format). On `refund.*` this describes the original payment
`total`	string	When available	Deprecated — Total after tax (display format). On `refund.*` this describes the original payment
`productName`	string	Always	Product name
`productDescription`	string	When set on product	Product description
`paymentId`	string	Payment & `refund.*` events	Payment ID. On `refund.*` this is the payment being refunded
`paymentStatus`	string	Payment & `refund.*` events	Payment status (`"succeeded"`, `"failed"`)
`paymentDate`	string	Payment & `refund.*` events	Payment date (ISO 8601 date, e.g., `"2026-03-10"`)
`paymentMethod`	string	Payment & `refund.*`, when known	Payment method type (e.g., `"card"`)
`paymentLast4`	string	Payment & `refund.*`, when known	Last 4 digits of the payment instrument
`paymentFailureReason`	string	Payment events, when set	Payment failure reason
`periodNumber`	number	Subscription events, `subscription.payment_succeeded` & subscription `refund.*`	Which billing period the event refers to, as reported by the payment channel. See the note below
`billingPeriod`	string	Subscription events	`"weekly"`, `"monthly"`, `"quarterly"`, `"yearly"`
`currentPeriodStart`	string	Subscription events	Current billing period start (ISO 8601 date)
`currentPeriodEnd`	string	Subscription events	Current billing period end (ISO 8601 date)
`canceledAt`	string	`subscription.canceling` / `canceled`	When cancellation was requested (ISO 8601) — not when access ends
`refundStatus`	string	`refund.*`	`"succeeded"` or `"failed"`
`refundReason`	string	`refund.*`, when set	Refund reason
`refundCreatedAt`	string	`refund.*`	Refund creation timestamp (ISO 8601)

Deprecated amount fields

amount / total / subtotal / taxAmount / taxRate / taxName name one thing but describe three: the charge on a payment event, the refund on a refund event, the plan’s price on a subscription status event. Each now has a replacement that names its own subject.

Deprecated	Payment events	`refund.*`	Subscription events
`amount`	`chargedAmount`	`refundedAmount`	`planPrice.total`
`total`	`listPrice.total`	`originalPayment.total`	`planPrice.total`
`subtotal`	`listPrice.subtotal`	`originalPayment.subtotal`	`planPrice.subtotal`
`taxAmount`	`listPrice.taxAmount`	`originalPayment.taxAmount`	`planPrice.taxAmount`
`taxRate`	`listPrice.taxRate`	`originalPayment.taxRate`	`planPrice.taxRate`
`taxName`	`listPrice.taxName`	`originalPayment.taxName`	`planPrice.taxName`

On payment events, amount changes value on 2026-09-21. From that date, order.completed and subscription.payment_succeeded report the amount the payment channel actually charged — the same value as chargedAmount — where they previously reported the list price recorded when the order was placed. The two differ only when a prorated credit or a zero-amount card check applies; for every other charge the value is identical. If the channel reported no amount for that charge, amount falls back to the list price total and chargedAmount is omitted.If you reconcile on amount == total, that assertion starts failing on payment events from this date. Switch to chargedAmount (what was taken) and listPrice.total (what was listed).Nothing else changes value. On refund.* and on subscription events amount is exactly what it was, and total / subtotal / taxAmount / taxRate / taxName are unchanged on every event.

Removal is no earlier than 2027-09-20 — 12 months from this notice — and ships with the next major version. Until then all six keep being delivered with unchanged types and trigger conditions. New integrations should read the replacement fields; existing integrations need no change to keep working. The deprecation is not signalled at runtime: the payload carries no deprecation metadata, and no Deprecation or Sunset headers are sent. This page and the SDK type definitions (@deprecated in TypeScript, // Deprecated: in Go) are where it is stated.

periodNumber is the billing period number the payment channel itself reports, passed through unchanged — Waffo never computes, counts or infers it.

1 on the first charge, N on the Nth renewal.
A failed charge still consumes a period. This is not a count of successful charges — use it to align with the period numbers you reconcile from the channel, not as a payment tally.
0 means the channel has authorized the subscription but has not charged it yet. It appears on a scheduled plan change before its switch time.
On subscription.payment_succeeded it is the period of that charge, and it is the one subscription-shaped field that event carries.
On refund.* it is the period of the refunded charge, not the period the refund happened in.
On subscription.canceling, subscription.uncanceled and subscription.plan_change_failed the channel sends no notification of its own, so the value is the subscription’s current period as last reported by the channel.
Not a deduplication key. Several events in the same period carry the same number. Deduplicate on id or eventId.
Absent on one-time orders and their refunds, and on subscriptions and payments created before this field shipped.

The same concept appears under three names, one per anchor. They are not three different numbers — each is this same channel value read at a different point:

Where you read it	Field	What the value is anchored to
Webhook payload	`data.periodNumber`	the entity the event is about (see the rules above)
GraphQL `Payment`	`periodNumber`	that charge — which period it paid for
GraphQL `SubscriptionOrder`	`currentPeriodNumber`	that subscription right now — which period it is in

The GraphQL subscription field is named differently on purpose: a subscription that has renewed three times is in period 3, while its first charge is forever periodNumber: 1. Reading one where you meant the other is the mistake the two names exist to prevent.

Amounts are display format strings, already converted from minor units. For example, USD "29.00" = 2900 cents; JPY "4500" = ¥4500. Zero is a legitimate value (a zero-amount card check) and is formatted the same way — "0.00" for USD, "0" for JPY. For an itemized display, use the block that matches the event: listPrice, originalPayment or planPrice.

taxRate in webhook payloads is a percentage number — 10 means 10%. The unit convention is being unified across the API surface; another surface (the TypeScript SDK types) still describes it as a decimal fraction. Tax collection is not enabled yet, so taxRate is 0 on every order today — read the value from the payload rather than hard-coding an assumption about its unit.

Payment amount in GraphQL

This is a defect fix, not a contract change. GraphQL’s Payment.amount has always been documented as the total charged to the buyer, but the implementation read the list price snapshot taken when the order was placed. It now reads what the payment channel actually charged — and so do amount filtering, amount sorting and the “fully refunded” test. All four read one source, so a list can no longer sort by one figure while the detail view shows another.Which payments change value. Only those where the two figures differ, which begins with the plan upgrades and downgrades that shipped on 2026-09-07 — before that date the list price and the actual charge never diverged on any charge. To date that is 7 live payments and 111 test payments. Every other payment reads exactly as it did. If you reconciled any of those charges from GraphQL after 2026-09-07, their amounts move to what the channel took, and a payment already refunded in full is now reported as fully refunded.When the channel reported no amount for a charge, the field falls back to the list price total and the fallback is logged server-side. Filtering and sorting fall back the same way, so such a payment is never silently missing from a filtered or sorted list.Webhook payloads are unaffected. No field on this page changes value; the only addition is originalChargedAmount on refund events.

Some Dashboard and Admin pages still show the list price. They read the list price snapshot directly rather than this field and have not been updated yet: the consumer invoice page, the Admin payment list, the Admin PSP reconciliation page, the merchant revenue page, the buyer portal, the sidebar, and the analytics page’s fallback. Until they are, one payment can show two different numbers — the GraphQL API and the webhook payload report what was charged, those pages report what was listed. Reconcile against the API, not the page.

A payment that collected nothing counts as fully refunded. “Fully refunded” is decided by comparing the refunds against the amount that payment collected, so a payment that collected 0 satisfies it with no refund existing at all: it reports isFullyRefunded: true and shows up in the “fully refunded” filter. These are charges that were never meant to take money — a zero-amount card check, the first charge of a free trial, or an order fully covered by a credit or coupon.Read it as the buyer was never charged, not money was returned. To tell the two apart, look for an actual refund: refundedAmount above zero, a non-empty refunds list, or refundStatus: refunded — that last one is decided purely by the existence of a succeeded refund and is unaffected by this fix.The rule itself is not new: an order whose list price was also 0 has always been reported this way. What the fix widens is the range — payments that collected 0 against a non-zero list price now join the set. That is 3 of the 7 affected live payments (39 of the 111 in test mode). No payment leaves the set because of this fix.

eventId Mapping

The eventId identifies the business entity that triggered the event:

Event Type	eventId maps to	Example
`order.completed`	Payment ID	`PAY_6eYCunG3IMmIgcQOnaXdoA`
`subscription.activated`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.payment_succeeded`	Payment ID	`PAY_6eYCunG3IMmIgcQOnaXdoA`
`subscription.renewed`	Order ID + period end	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-renewed-2026-05-10`
`subscription.recovered`	Order ID + event timestamp	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-04-12T08:30:00.000Z`
`subscription.canceling`	Order ID + event timestamp	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-04-10T08:31:00.000Z`
`subscription.uncanceled`	Order ID + event timestamp	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-04-10T08:31:00.000Z`
`subscription.plan_changed`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.plan_change_scheduled`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.plan_change_failed`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.canceled`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.past_due`	Order ID + event timestamp	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-04-10T08:31:00.000Z`
`refund.succeeded`	Refund ID	`REF_4cWAtlE1GKkGebONl9Xbnx`
`refund.failed`	Refund ID	`REF_4cWAtlE1GKkGebONl9Xbnx`

Some events can happen more than once on the same subscription, so their eventId carries a suffix and each occurrence becomes its own delivery.Four events append the event timestamp (full ISO 8601): subscription.canceling, subscription.uncanceled, subscription.past_due and subscription.recovered — a subscriber can cancel and un-cancel, or fall overdue and recover, any number of times.subscription.renewed appends the new period end instead, so consecutive renewals each get their own key. That suffix is a date at day granularity (YYYY-MM-DD), so two period rolls inside the same calendar day would collapse into one delivery — reachable only with compressed test billing cycles, not with real weekly or monthly billing.Every other event uses the bare entity ID, because it happens at most once per entity.

Correlating a Payment with Its Billing Period

A renewal produces two independent deliveries: subscription.payment_succeeded (keyed to the charge) and subscription.renewed (keyed to the order). They leave in the same batch, but neither order nor spacing is guaranteed, so do not join them at receive time. Store each on its own, then correlate on data.orderId + data.periodNumber: the charge for period N and the renewal into period N normally carry the same pair, and the join is unaffected by reordering, delays and retries. Both values are the channel’s own period number passed through unchanged, so this consistency comes from the channel’s numbering, not from a Waffo guarantee — keep the timestamp fallback below for the rare case they disagree. The same pair ties subscription.activated to the first charge (periodNumber: 1) and subscription.recovered to the charge that cleared the overdue period. periodNumber is absent on subscriptions created before the field shipped. For those, fall back to data.orderId plus the top-level timestamp (event creation time, unchanged by retries) matched within a few minutes. In both cases deduplicate each event type on id or eventId before correlating.

Event Types

Overview

Event	Trigger	eventId
`order.completed`	One-time order payment succeeded	Payment ID
`subscription.activated`	Subscription first payment succeeded	Order ID
`subscription.payment_succeeded`	Any subscription charge succeeded — first payment and renewals. Pure payment event: no subscription period or status	Payment ID
`subscription.renewed`	Current billing period rolled forward (renewal)	Order ID + period end
`subscription.recovered`	An overdue subscription was brought back to active by a successful retry	Order ID + event timestamp
`subscription.canceling`	Cancellation requested — active until period ends	Order ID
`subscription.uncanceled`	Cancellation withdrawn	Order ID
`subscription.plan_changed`	Plan change took effect (upgrade/downgrade)	Order ID
`subscription.plan_change_scheduled`	Plan change confirmed, effective next billing period	Order ID
`subscription.plan_change_failed`	Plan change did not complete, the current plan stays in effect	Order ID
`subscription.canceled`	Subscription terminated (period ended)	Order ID
`subscription.past_due`	Renewal payment failed	Order ID + event timestamp
`refund.succeeded`	Refund completed	Refund ID
`refund.failed`	Refund failed	Refund ID

subscription.plan_changed fires when a subscription switches to another plan. direction is upgrade, downgrade, or same_price; planChange.chargedAmount is what was actually charged this time, which differs from the plan’s list price when a prorated credit or a merchant-specified amount applies.subscription.plan_change_scheduled fires when the change is confirmed but effective next period, and subscription.plan_change_failed when it does not complete. All three are live in production — handle all three, or you will miss outcomes. Which ones you receive depends on the timing tier:

Outcome	Events, in order
Immediate change	`subscription.plan_changed` only
Next-period change	`subscription.plan_change_scheduled` at confirmation, then `subscription.plan_changed` at the switch
Change did not complete	`subscription.plan_change_failed` only — the original plan stays in effect

A next-period change therefore produces two events for one change, and the plan takes effect only on the second. Do not grant the new plan’s access on plan_change_scheduled.

For where each event sits in the order, subscription, and refund lifecycles — and for the transitions that emit nothing — see Lifecycle and Trigger Timing.

Event Details

order.completed

Trigger: One-time order payment succeeds for the first time.Body:

{
  "id": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "order.completed",
  "eventId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "chargedAmount": "98.00",
    "amount": "98.00",
    "taxAmount": "8.00",
    "taxRate": 8,
    "taxName": "Consumption Tax",
    "subtotal": "100.00",
    "total": "108.00",
    "listPrice": {
      "total": "108.00",
      "subtotal": "100.00",
      "taxAmount": "8.00",
      "taxRate": 8,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242"
  }
}

amount equals chargedAmount here — what the channel actually took. listPrice is what the order was priced at; the two differ in this example because a prorated credit applied. No subscription or refund fields appear. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, paymentMethod, paymentLast4, chargedAmount, listPrice.Recommended actions:

Deliver digital goods (license keys, download links, activation codes)
Update your order management system
Send customer confirmation (if not using Waffo’s built-in emails)

The same order only triggers order.completed once. Refunds are notified via refund.succeeded / refund.failed.

subscription.activated

Trigger: First payment on a new subscription succeeds (pending → active).Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "subscription.activated",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10"
  }
}

amount is the subscription’s regular-phase price, not what was charged. With a trial or an introductory discount the first charge differs — use subscription.payment_succeeded for the amount actually collected.

This event is keyed to the order, not to a charge — no paymentId or other payment fields appear. The billing period is written and the event published inside the same request, so billingPeriod, currentPeriodStart and currentPeriodEnd are always present. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, planPrice.Recommended actions:

Provision the subscriber’s account and grant access
Record the subscription start date

Fires only on the first pending → active transition. The same first payment also emits subscription.payment_succeeded for the charge itself — see Subscription Lifecycle.

subscription.payment_succeeded

Trigger: A subscription charge succeeds — the first payment, every renewal, and the charge that clears an overdue period.Body:

{
  "id": "PAY_7fZDvoH4JNnJhdRPobYepB",
  "timestamp": "2026-04-10T08:30:00.000Z",
  "eventType": "subscription.payment_succeeded",
  "eventId": "PAY_7fZDvoH4JNnJhdRPobYepB",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "chargedAmount": "98.00",
    "amount": "98.00",
    "taxAmount": "8.00",
    "taxRate": 8,
    "taxName": "Consumption Tax",
    "subtotal": "100.00",
    "total": "108.00",
    "listPrice": {
      "total": "108.00",
      "subtotal": "100.00",
      "taxAmount": "8.00",
      "taxRate": 8,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "paymentId": "PAY_7fZDvoH4JNnJhdRPobYepB",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-04-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "periodNumber": 2
  }
}

Unlike the other subscription.* events, this one is keyed to a charge, so it carries the payment fields. amount is what was charged for this period and equals chargedAmount; listPrice is the price the period was billed at, which a prorated credit or a zero-amount card check can make higher. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, paymentMethod, paymentLast4, chargedAmount, listPrice.

This is a pure payment event. It carries no billingPeriod, currentPeriodStart, currentPeriodEnd, canceledAt or orderStatus — those describe the subscription, not the charge, and now travel on the subscription domain events, where they are written and published inside the same request and no longer arrive empty.If your handler reads any of those five fields here:

You used it for	Read it from instead
Extending access after a renewal	`subscription.renewed` — emitted whenever the current period actually rolls forward
Detecting the first paid period	`subscription.activated` — now always carries the full period
Knowing the subscription is healthy	`subscription.recovered` — emitted when a retried charge brings a past-due subscription back to active
Reading the subscription status	any subscription domain event (`orderStatus`), or query the order via GraphQL

periodNumber is the exception: it describes this charge, so it stays on this event. It tells you which billing period was just paid for.A handler that only uses the payment fields and orderId needs no change.

Recommended actions:

Record the receipt for this charge
Generate an invoice for this billing cycle
Extend the service period on subscription.renewed, and restore full access on subscription.recovered

subscription.renewed

Trigger: The current billing period rolls forward — the paid period just ended and the next one began. The first period of a subscription is not a renewal and does not emit this event.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-10T08:30:02.000Z",
  "eventType": "subscription.renewed",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz-renewed-2026-05-10",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 2,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-10",
    "currentPeriodEnd": "2026-05-10"
  }
}

No payment fields on this event — it reports the new period, not the charge. amount is the subscription’s per-period price. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, planPrice.Recommended actions:

Extend the service period to the new currentPeriodEnd

Deduplication: eventId carries the new period end, so consecutive renewals of the same subscription each get their own delivery, while a redelivered provider notification does not produce a second one.

subscription.recovered

Trigger: A retried charge succeeds on an overdue subscription and brings it back to active (past_due → active). Closes the loop opened by subscription.past_due. First payments and ordinary renewals do not emit it.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-05-12T09:15:00.000Z",
  "eventType": "subscription.recovered",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-05-12T09:15:00.000Z",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 2,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-10",
    "currentPeriodEnd": "2026-05-10"
  }
}

No payment fields on this event — the charge itself is reported by subscription.payment_succeeded, which is delivered independently for the same retry. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, planPrice.Recommended actions:

Restore any access you degraded on subscription.past_due

Deduplication: eventId carries the event timestamp, so a subscription that goes overdue and recovers repeatedly produces one delivery per recovery.

subscription.canceling

Trigger: Customer or merchant requests cancellation. The subscription remains active until the current paid period ends.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-25T11:02:00.000Z",
  "eventType": "subscription.canceling",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "canceling",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10",
    "canceledAt": "2026-03-25T11:02:00.000Z"
  }
}

canceledAt is when cancellation was requested, not when access ends. The customer has paid through currentPeriodEnd — revoking access at canceledAt cuts off service they already paid for.

No payment fields on this event. amount is the subscription’s per-period price, not a charge. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, currentPeriodStart, currentPeriodEnd, planPrice.Recommended actions:

Show “Subscription expires on [date]” notice
Offer a retention flow (e.g., discounted renewal)
Do not revoke access — the customer has paid for the current period

The customer can withdraw the cancellation before the period ends (triggers subscription.uncanceled).

subscription.uncanceled

Trigger: Cancellation is withdrawn before the current period ends.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-28T14:20:00.000Z",
  "eventType": "subscription.uncanceled",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10"
  }
}

No payment fields on this event. canceledAt is cleared when the cancellation is withdrawn, so it does not appear. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, currentPeriodStart, currentPeriodEnd, planPrice.Recommended actions:

Remove the “expiring soon” notice
Restore auto-renewal status

subscription.plan_changed

Trigger: Subscription product changes (upgrade or downgrade).Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-02T10:05:00.000Z",
  "eventType": "subscription.plan_changed",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "49.00",
    "taxAmount": "4.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "44.10",
    "total": "49.00",
    "planPrice": {
      "total": "49.00",
      "subtotal": "44.10",
      "taxAmount": "4.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Business Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-02",
    "currentPeriodEnd": "2026-05-02",
    "planChange": {
      "direction": "upgrade",
      "oldPlanName": "Starter Plan",
      "oldAmount": "29.00",
      "newPlanName": "Business Plan",
      "newAmount": "49.00",
      "chargedAmount": "24.50",
      "effectiveDate": "2026-04-02T10:04:58.312Z"
    }
  }
}

The top-level fields describe the state after the change; data.planChange carries the before/after pair, so you do not need to keep your own record of the previous plan. direction is upgrade, downgrade, or same_price.amount is not what the buyer paid. The top-level amount / total / subtotal / taxAmount are the new plan’s list price; planChange.chargedAmount is what was actually charged this time. On a plan change the two always differ — either a prorated credit applies, or the merchant specified the amount. Reconcile against chargedAmount.planChange appears only on plan-change events; the data of every other event does not carry the key at all. Each field inside it may be null when unknown: chargedAmount is null before a successful payment, effectiveDate may be null for an immediate change, and direction falls back to null rather than passing through an unrecognized value. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, currentPeriodStart, currentPeriodEnd, planPrice.Recommended actions:

Update the customer’s access level (add/remove features)
Update billing records

subscription.plan_change_scheduled

Trigger: A plan change is confirmed but takes effect at the start of the next billing period. The customer keeps the current plan until then.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-02T10:05:00.000Z",
  "eventType": "subscription.plan_change_scheduled",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "pending",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "starter" },
    "productMetadata": {},
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Starter Plan",
    "periodNumber": 0,
    "billingPeriod": "monthly",
    "planChange": {
      "direction": "downgrade",
      "oldPlanName": "Business Plan",
      "oldAmount": "49.00",
      "newPlanName": "Starter Plan",
      "newAmount": "29.00",
      "chargedAmount": null,
      "effectiveDate": "2026-05-02T00:00:01.000Z"
    }
  }
}

The change has not taken effect yet. effectiveDate is the future moment the new plan starts, orderStatus is pending, and currentPeriodStart / currentPeriodEnd are absent because the new subscription has no billing period until then. chargedAmount is null — a next-period change is charged at the switch, not at confirmation. Do not grant the new plan’s access on this event; wait for subscription.plan_changed.The id and eventId are the new subscription order, which is also the order subscription.plan_changed will carry at the switch. The customer’s currently active subscription is a different order and is not named in this payload. That order is marked for the upcoming switch at this point, but subscription.canceling is not emitted for it — this event is the only signal you get.If several confirmations arrive before the switch, you receive one delivery — they collapse on eventType + eventId. The later plan_changed is a different event type and is never collapsed into it.Recommended actions:

Record the pending change and its effectiveDate
Leave the current plan’s access untouched
Optionally tell the customer when the new plan starts

subscription.plan_change_failed

Trigger: A plan change did not complete — the payment was not authorized, or the channel reported a failure. The original plan stays in effect.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-02T10:05:00.000Z",
  "eventType": "subscription.plan_change_failed",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "canceled",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "49.00",
    "taxAmount": "4.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "44.10",
    "total": "49.00",
    "planPrice": {
      "total": "49.00",
      "subtotal": "44.10",
      "taxAmount": "4.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Business Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "planChange": {
      "direction": null,
      "oldPlanName": "Starter Plan",
      "oldAmount": null,
      "newPlanName": "Business Plan",
      "newAmount": null,
      "chargedAmount": null,
      "effectiveDate": null
    }
  }
}

planChange is mostly null on this event, by design. Nothing took effect, so there is no direction, no effective moment, and no amounts to report: only oldPlanName and newPlanName are populated, and the other five fields are always null. A handler written against the subscription.plan_changed body will read nulls here — branch on eventType before touching those fields.

orderStatus is canceled, but the customer has not lost their subscription. The cancelled order is the new one that failed to open; the original subscription is untouched and still active. Revoking access on this event is a bug. A genuine cancellation always arrives as subscription.canceled.

A retry creates a fresh subscription order, so a second failure arrives with a different id / eventId rather than collapsing into this one.Recommended actions:

Leave the customer’s access exactly as it is
Clear any pending change you recorded from subscription.plan_change_scheduled
Optionally prompt the customer to try the change again

subscription.canceled

Trigger: Subscription is terminated — the paid period has ended and no further renewals will occur.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-10T00:05:00.000Z",
  "eventType": "subscription.canceled",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "canceled",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 1,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10",
    "canceledAt": "2026-03-25T11:02:00.000Z"
  }
}

No payment fields on this event. canceledAt is when cancellation was requested, which is earlier than this event — the subscription stayed active until currentPeriodEnd. amount is the per-period price, not a final charge. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, currentPeriodStart, currentPeriodEnd, canceledAt, planPrice.Recommended actions:

Revoke access (or downgrade to a free tier)
Retain data for a grace period (in case the customer re-subscribes)
Send a “subscription ended” confirmation

This is a terminal state. The subscription is irreversibly ended.

subscription.past_due

Trigger: Renewal payment fails and the subscription enters an overdue state.Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-05-10T08:31:00.000Z",
  "eventType": "subscription.past_due",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-05-10T08:31:00.000Z",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "past_due",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "planPrice": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "periodNumber": 2,
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-10",
    "currentPeriodEnd": "2026-05-10"
  }
}

eventId carries the event timestamp as a suffix, so each time the subscription goes overdue gets its own delivery. No payment fields appear, so the payload does not say why the charge failed; amount is the amount due. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, taxRate, taxName, subtotal, total, currentPeriodStart, currentPeriodEnd, planPrice.Recommended actions:

Notify the customer to update their payment method
Optionally degrade the service (limit features rather than fully revoking)
Do not revoke access immediately — the PSP may retry the charge automatically

Deduplication: One delivery per entry into the overdue state. The subscription only enters past_due again after a successful charge has brought it back to active (which emits subscription.recovered), so repeated retry failures within one overdue spell do not fan out into repeated events.

refund.succeeded

Trigger: Refund has been completed and funds returned.Body (partial refund: 10.00 refunded against a 29.00 original payment):

{
  "id": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "timestamp": "2026-03-12T09:15:23.481Z",
  "eventType": "refund.succeeded",
  "eventId": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "refundTicketMerchantExternalId": "REF-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "refundedAmount": "10.00",
    "amount": "10.00",
    "taxAmount": "0.00",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "originalChargedAmount": "29.00",
    "originalPayment": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "periodNumber": 1,
    "refundStatus": "succeeded",
    "refundReason": "Customer requested refund",
    "refundCreatedAt": "2026-03-12T09:15:00.000Z"
  }
}

amount is the refund amount; total is the original payment. On a partial refund they differ — record the refund with refundedAmount (or the deprecated amount), never total.

subtotal / total / taxRate / taxName describe the original payment and are kept for comparison. taxAmount is always "0" because refunds carry no tax breakdown — the original order’s real tax is in originalPayment.taxAmount. Record the refund with refundedAmount and the order it came from with originalPayment. Compute how much of this payment is still refundable from originalChargedAmount, not from originalPayment.total — the former is what the buyer was actually charged, and refunding up to the list price is rejected by the channel whenever the two differ (a payment charged 5.00 against a 50.00 list price accepts at most 5.00). paymentId identifies the charge being refunded — for a subscription this is the specific renewal, which is how you tell which period was refunded. The payload does not report how much of the payment has been refunded in total, so track that yourself if a payment can be refunded more than once. Omitted when empty: productDescription, merchantProvidedBuyerIdentity, billingDetail, orderMerchantExternalId, refundTicketMerchantExternalId, taxRate, taxName, subtotal, total, paymentMethod, paymentLast4, refundReason, refundedAmount, originalChargedAmount, originalPayment.Recommended actions:

Revoke delivered digital goods (revoke licenses, disable downloads)
Update order status to “refunded”

refund.failed

Trigger: Refund processing failed.Body:

{
  "id": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "timestamp": "2026-03-12T09:15:23.481Z",
  "eventType": "refund.failed",
  "eventId": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "refundTicketMerchantExternalId": "REF-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "refundedAmount": "10.00",
    "amount": "10.00",
    "taxAmount": "0.00",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "originalChargedAmount": "29.00",
    "originalPayment": {
      "total": "29.00",
      "subtotal": "26.10",
      "taxAmount": "2.90",
      "taxRate": 10,
      "taxName": "Consumption Tax"
    },
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "periodNumber": 1,
    "refundStatus": "failed",
    "refundReason": "Customer requested refund",
    "refundCreatedAt": "2026-03-12T09:15:00.000Z"
  }
}

No money moved. refundedAmount (and the deprecated amount) is the amount that was attempted — do not record it as a refund.

Same shape as refund.succeeded otherwise. refundStatus is the only field that distinguishes the two events, so branch on it rather than on the presence of any field. The payload does not carry a failure cause; check the refund ticket in the Dashboard. Omitted when empty: same list as refund.succeeded.Recommended actions:

Log the failure for manual review
Do not revoke goods (the refund was not completed)

Lifecycle and Trigger Timing

An event fires when the underlying business fact is settled — not when the buyer clicks. Payment events are emitted after the payment provider confirms the charge; subscription state events are emitted after the provider confirms the state change. Delivery to your endpoint then normally completes within a few seconds. The timestamp field carries the moment the event was created. Retries reuse it, so it does not move with delivery attempts.

Delivery Timeline

Treat the event — not the checkout redirect — as the point where money is confirmed. A buyer can close the browser before the redirect; the event still arrives.

One-Time Order Lifecycle

Moment	Event
Payment confirmed	`order.completed`
Payment declined — the order stays payable	None
Checkout expired or the buyer canceled	None
Refund settled against the payment	`refund.succeeded` / `refund.failed`

A declined payment leaves the order in pending, so the buyer can pay again on the same order. order.completed fires once per order — the retry that finally succeeds is the one that emits it.

Subscription Lifecycle

Moment	Event
First payment confirmed	`subscription.activated` and `subscription.payment_succeeded`
Renewal confirmed	`subscription.payment_succeeded` and `subscription.renewed`
Overdue subscription pays successfully	`subscription.payment_succeeded` and `subscription.recovered`
Renewal declined while `active`	`subscription.past_due`
Renewal declined again while `past_due`	`subscription.canceled` — the subscription is terminated
Cancellation requested	`subscription.canceling`, immediately
Cancellation withdrawn	`subscription.uncanceled`, immediately
Termination confirmed	`subscription.canceled`, around `currentPeriodEnd`
Billing period rolled forward	`subscription.renewed`
Canceled or timed out before the first payment	None

The first payment emits two events: subscription.activated (keyed to the order) and subscription.payment_succeeded (keyed to the charge). They are delivered independently, so neither order nor spacing is guaranteed. Provision access on activated and record the receipt on payment_succeeded — handling both as “a new subscriber” runs your onboarding twice.

Cancellation splits into two moments. subscription.canceling fires the instant cancellation is requested; the termination itself is scheduled for the end of the paid period, and subscription.canceled fires once the payment provider confirms it — around currentPeriodEnd, not at the moment of the request. Between the two, the subscription is still active and the customer can withdraw the cancellation. An overdue subscription is terminated by the next failed renewal: the first decline moves active → past_due and emits subscription.past_due; a further decline in past_due ends the subscription and emits subscription.canceled.

Terminal State	Meaning	Event
`canceled`	Terminated after activation, or canceled before the first payment	`subscription.canceled` — only if it had been active
`closed`	The payment window elapsed without a first payment	None
`expired`	Fixed-term subscription reached its end	None

Refund Lifecycle

Refund events fire at the last step only — when the provider settles the outcome. Creating, approving, rejecting, or resubmitting a refund ticket produces no webhook, so a ticket sitting in review is invisible to your endpoint until it settles. Refunds requested through the API are auto-approved and go straight to processing; see Refund Endpoints for the ticket states and how to query them.

When No Event Fires

Situation	Why
One-time payment declined	The order stays `pending` and remains payable — nothing has settled
Checkout expired or the buyer canceled	The order ends `canceled` without ever being paid
Subscription canceled or timed out before its first payment	It never activated, so `canceled` / `closed` carry no notification
Fixed-term subscription reached its end	The end date was known at purchase
Refund ticket created, approved, rejected, or resubmitted	Only the settled outcome is reported

Signature Verification

Always verify signatures in production. Without verification, anyone can send forged requests to your endpoint.

Algorithm

Parse t (timestamp in ms) and v1 (Base64 signature) from X-Waffo-Signature header
Build signature input: `${t}.${rawRequestBody}`
Verify v1 using RSA-SHA256 with the Waffo public key
(Recommended) Check that t is within 45 minutes of current time. NOT 5: retries replay the ORIGINAL signature header — t is never re-stamped, and the final retry lands 31+ minutes after first delivery, so a 5-minute window rejects legitimate retries with 401. Replay protection comes from deduplicating on the payload id, not from tightening this window

Using the SDK (Recommended)

The SDK embeds public keys, auto-detects the environment, and handles format normalization:

import { verifyWebhook, WebhookEventType } from "@waffo/pancake-ts";

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook(
      req.body.toString("utf-8"),
      req.headers["x-waffo-signature"] as string,
    );

    res.status(200).send("OK");

    switch (event.eventType) {
      case WebhookEventType.OrderCompleted:
        // Deliver digital goods
        break;
      case WebhookEventType.SubscriptionActivated:
        // Provision subscription access
        break;
      case WebhookEventType.SubscriptionCanceled:
        // Revoke access
        break;
    }
  } catch {
    res.status(401).send("Invalid signature");
  }
});

See the full SDK Webhook documentation.

Manual Verification

If you’re not using the TypeScript SDK, implement signature verification manually.

const crypto = require('crypto');

// From Dashboard → API & Development → Webhook Public Key (PEM format)
const WAFFO_WEBHOOK_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----`;

function parseSignatureHeader(header) {
  const parts = {};
  for (const pair of header.split(',')) {
    const [key, ...rest] = pair.split('=');
    parts[key.trim()] = rest.join('=').trim();
  }
  return parts;
}

function verifyWebhookSignature(rawBody, signatureHeader, publicKey) {
  const { t, v1 } = parseSignatureHeader(signatureHeader);
  if (!t || !v1) return false;

  // 45 minutes, NOT 5: retries carry the original t (it is never re-signed),
  // and the last retry arrives 31+ minutes after first delivery. True replay
  // protection is deduplicating on the payload id.
  const tolerance = 45 * 60 * 1000;
  if (Math.abs(Date.now() - Number(t)) > tolerance) return false;

  // Verify RSA-SHA256 signature
  const signatureInput = `${t}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signatureInput);
  return verifier.verify(publicKey, v1, 'base64');
}

app.post('/webhooks',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-waffo-signature'];
    const rawBody = req.body.toString('utf-8');

    if (!sig || !verifyWebhookSignature(rawBody, sig, WAFFO_WEBHOOK_PUBLIC_KEY)) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(rawBody);
    res.status(200).send('OK');

    // Process asynchronously
    handleEvent(event).catch(console.error);
  }
);

async function handleEvent(event) {
  switch (event.eventType) {
    case 'order.completed':
      await grantAccess(event.data.buyerEmail, event.data.productName);
      break;
    case 'subscription.activated':
      await createSubscription(event.data.buyerEmail, event.data.orderId);
      break;
    case 'subscription.payment_succeeded':
      await recordReceipt(event.data.orderId, event.data.paymentId);
      break;
    case 'subscription.renewed':
      await extendSubscription(event.data.orderId, event.data.currentPeriodEnd);
      break;
    case 'subscription.recovered':
      await restoreAccess(event.data.orderId);
      break;
    case 'subscription.canceling':
      await markCanceling(event.data.orderId);
      break;
    case 'subscription.canceled':
      await revokeAccess(event.data.orderId);
      break;
    case 'subscription.past_due':
      await notifyPastDue(event.data.buyerEmail, event.data.orderId);
      break;
    case 'refund.succeeded':
      await revokeAccess(event.data.orderId);
      break;
    case 'refund.failed':
      await flagForReview(event.data.orderId);
      break;
  }
}

import json, time
from base64 import b64decode
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from flask import Flask, request

app = Flask(__name__)

WAFFO_WEBHOOK_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----"""

def verify_webhook_signature(raw_body, signature_header, public_key_pem):
    parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False

    # 45 minutes, NOT 5: retries carry the original t (never re-signed), and
    # the last retry arrives 31+ minutes after first delivery. True replay
    # protection is deduplicating on the payload id.
    if abs(int(time.time() * 1000) - int(t)) > 45 * 60 * 1000:
        return False

    signature_input = f"{t}.{raw_body}".encode("utf-8")
    public_key = serialization.load_pem_public_key(public_key_pem.encode("utf-8"))
    try:
        public_key.verify(b64decode(v1), signature_input, padding.PKCS1v15(), hashes.SHA256())
        return True
    except Exception:
        return False

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-Waffo-Signature", "")
    raw_body = request.get_data(as_text=True)

    if not verify_webhook_signature(raw_body, sig, WAFFO_WEBHOOK_PUBLIC_KEY):
        return "Invalid signature", 401

    event = json.loads(raw_body)
    # Process event...
    return "OK", 200

package main

import (
	"crypto"
	"crypto/rsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const waffoPublicKeyPEM = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----`

func verifyWebhookSignature(rawBody []byte, signatureHeader string) bool {
	var t, v1 string
	for _, pair := range strings.Split(signatureHeader, ",") {
		parts := strings.SplitN(pair, "=", 2)
		if len(parts) != 2 { continue }
		switch strings.TrimSpace(parts[0]) {
		case "t": t = strings.TrimSpace(parts[1])
		case "v1": v1 = strings.TrimSpace(parts[1])
		}
	}
	if t == "" || v1 == "" { return false }

	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil || math.Abs(float64(time.Now().UnixMilli()-ts)) > 45*60*1000 {
		return false
	}

	block, _ := pem.Decode([]byte(waffoPublicKeyPEM))
	if block == nil { return false }
	pub, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil { return false }
	rsaPub, ok := pub.(*rsa.PublicKey)
	if !ok { return false }

	hash := sha256.Sum256([]byte(fmt.Sprintf("%s.%s", t, string(rawBody))))
	sig, err := base64.StdEncoding.DecodeString(v1)
	if err != nil { return false }
	return rsa.VerifyPKCS1v15(rsaPub, crypto.SHA256, hash[:], sig) == nil
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	rawBody, _ := io.ReadAll(r.Body)
	if !verifyWebhookSignature(rawBody, r.Header.Get("X-Waffo-Signature")) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))
}

func main() {
	http.HandleFunc("/webhooks", webhookHandler)
	http.ListenAndServe(":8080", nil)
}

You must use the raw request body for signature verification. If your framework parses JSON automatically, the signature check will fail. Ensure you capture the unmodified raw string before verification.

Response Requirements

Return 2xx status code (recommended: 200)
Respond within 10 seconds
Response body does not matter

// Recommended: respond immediately, process async
app.post('/webhooks', (req, res) => {
  res.status(200).send('OK');
  processEventAsync(req.body);
});

Non-2xx responses or timeouts trigger retries.

Retry Policy

Failed deliveries are retried automatically with exponential backoff:

Item	Details
Retries	Up to 3 (4 total attempts including the first)
Backoff	Scheduled by the delivery queue with its default exponential backoff; Waffo does not configure the intervals, and there is no manual resend
Timeout	Non-2xx or no response within the timeout window
Final failure	Delivery marked as `failed` after all retries exhausted

Delivery Status

Status	Description
`pending`	Created, awaiting delivery or retrying
`success`	Delivered successfully (your server returned 2xx)
`failed`	All retries exhausted

View delivery history in the Dashboard webhook logs, including status, HTTP response code, and response body (truncated to 1000 characters).

Handling Duplicates

Network issues may cause the same event to be delivered multiple times. Ensure your event handling is idempotent. Use the eventType + eventId combination (which has a unique constraint in the system) for deduplication:

async function handleEvent(event) {
  const exists = await db.query(
    'SELECT 1 FROM processed_webhooks WHERE event_type = $1 AND event_id = $2',
    [event.eventType, event.eventId]
  );
  if (exists.rows.length > 0) return; // Already processed

  await processEventLogic(event);

  await db.query(
    'INSERT INTO processed_webhooks (event_type, event_id, processed_at) VALUES ($1, $2, NOW())',
    [event.eventType, event.eventId]
  );
}

The same business event (identical eventType + eventId) only creates one delivery record — it won’t be duplicated. However, a single delivery may reach your endpoint multiple times due to retries.

Best Practices

Always verify signatures

Always verify X-Waffo-Signature. Without verification, anyone can send forged requests to your endpoint.

Use HTTPS

Production webhook URLs must use HTTPS to protect data in transit.

Respond fast, process async

Return 200 immediately and process business logic in the background. Slow responses cause unnecessary retries.

Deduplicate with eventType + eventId

Use the eventType + eventId combination to deduplicate. Ensure the same delivery processed multiple times has no side effects.

Check timestamps

Allow t up to 45 minutes old. Retries replay the original signature header — t is never re-stamped — and the final retry lands 31+ minutes after first delivery, so a 5-minute window turns your own outage recovery into 401s. Deduplicate on the payload id for replay protection instead; it is unique per event and stable across retries.

Use the correct environment key

Test and Production use different key pairs. Match the public key to the mode field in the payload.

Log incoming payloads

Store received payloads for debugging. The Dashboard also provides delivery log queries.

Handle all subscribed events

Add a branch for every event you subscribe to, even if you don’t need it yet. Return 200 for unhandled events — returning an error triggers unnecessary retries.

Testing

Send Test Events (Recommended)

Use the Dashboard “Send Test Event” button to send test events without triggering real transactions. Test events use fixed sample data (amount 0, taxAmount 0, product “[TEST] Webhook Verification”) and are always signed with the Test key. All 10 event types are supported — test each one to verify your handler.

periodNumber behaves differently in test events than in production.

Event in a test send	`periodNumber`
Any `subscription.*` event (including `subscription.payment_succeeded`)	always `1`
`refund.succeeded` / `refund.failed`	not sent
`order.completed`	not sent

A test send has no subscription behind it, so the refund sample cannot say which period it refunds. In production a refund of a subscription charge does carry periodNumber — the period of the charge being refunded. Do not conclude from a test event that subscription refunds lack the field; code your handler to read it when present.

Use Test Mode

Configure the Test environment Webhook URL and events in the Dashboard
Perform real operations in Test mode (create orders, process payments)
Events are sent to your Test Webhook URL with Test signing keys

Local Development

Use a tunnel to expose your local server:

ngrok http 8080
# Use the generated URL as your Test Webhook URL
# e.g., https://abc123.ngrok.io/webhooks

Delivery Logs

View webhook delivery history in the Dashboard:

Status: pending / success / failed
HTTP status code: Your server’s response code
Response body: Your server’s response (truncated to 1000 chars)
Timestamp: Last delivery attempt

FAQ

Not receiving webhooks

Confirm the Webhook URL is configured in the Dashboard and publicly accessible
Confirm you’ve subscribed to the correct event types
Confirm you’re using the correct environment (Test / Production)
Check that your firewall allows requests from Waffo
Try the Dashboard “Send Test Event” to isolate the issue

Signature verification fails

Confirm you’re using the correct environment’s public key (Test vs Production)
Confirm you’re using the raw request body — not a parsed JSON object
Check if any middleware or proxy modified the request body
Confirm the signature input format is ${t}.${rawBody} (timestamp + dot + raw body)
If using TypeScript, switch to the @waffo/pancake-ts SDK — it handles key selection and format normalization automatically

Receiving duplicate events

This is normal retry behavior. If your endpoint returned non-2xx or timed out, the system retries. Ensure your handler is idempotent — use the eventType + eventId combination for deduplication.

Why does the first subscription payment produce two events?

The first charge settles two facts at once: the subscription becomes active (subscription.activated, keyed to the order) and a payment was collected (subscription.payment_succeeded, keyed to the charge). They travel independently, so neither order nor spacing is guaranteed. Provision access on activated, record the receipt on payment_succeeded, and your first-payment path runs exactly once.

When exactly does `subscription.canceled` arrive?

Around currentPeriodEnd — not when the cancellation was requested. Requesting cancellation emits subscription.canceling immediately and schedules the termination for the end of the paid period; subscription.canceled follows once the payment provider confirms the termination. Use currentPeriodEnd from the canceling payload to know when access should end.

Difference between `subscription.canceling` and `subscription.canceled`

canceling: Cancellation requested, but the current paid period hasn’t ended. The subscription is still active and the customer can withdraw the cancellation (triggers uncanceled). Do not revoke access.
canceled: Subscription is terminated. This is irreversible — revoke access or downgrade permissions.

What does `data.amount` mean for different events?

All events: data.amount is the transaction amount for that specific event (including tax):

order.completed / subscription.activated — Payment amount
subscription.payment_succeeded — Amount charged for this period
subscription.renewed / subscription.recovered — Subscription per-period amount
subscription.past_due — Amount due for this period
refund.succeeded / refund.failed — Refund amount
subscription.canceling / subscription.canceled / subscription.uncanceled — Subscription per-period amount

​Overview

​Setup

​Environment Isolation

​Payload Format

​Headers

​Body

​Top-level Fields

​data Fields

​Deprecated amount fields

​Payment amount in GraphQL

​eventId Mapping

​Correlating a Payment with Its Billing Period

​Event Types

​Overview

​Event Details

​Lifecycle and Trigger Timing

​Delivery Timeline

​One-Time Order Lifecycle

​Subscription Lifecycle

​Refund Lifecycle

​When No Event Fires

​Signature Verification

​Algorithm

​Using the SDK (Recommended)

​Manual Verification

​Response Requirements

​Retry Policy

​Delivery Status

​Handling Duplicates

​Best Practices

​Testing

​Send Test Events (Recommended)

​Use Test Mode

​Local Development

​Delivery Logs

​FAQ

​Not receiving webhooks

​Signature verification fails

​Receiving duplicate events

​Why does the first subscription payment produce two events?

​When exactly does subscription.canceled arrive?

​Difference between subscription.canceling and subscription.canceled

​What does data.amount mean for different events?

Overview

Setup

Environment Isolation

Payload Format

Headers

Body

Top-level Fields

`data` Fields

Deprecated amount fields

Payment amount in GraphQL

eventId Mapping

Correlating a Payment with Its Billing Period

Event Types

Overview

Event Details

Lifecycle and Trigger Timing

Delivery Timeline

One-Time Order Lifecycle

Subscription Lifecycle

Refund Lifecycle

When No Event Fires

Signature Verification

Algorithm

Using the SDK (Recommended)

Manual Verification

Response Requirements

Retry Policy

Delivery Status

Handling Duplicates

Best Practices

Testing

Send Test Events (Recommended)

Use Test Mode

Local Development

Delivery Logs

FAQ

Not receiving webhooks

Signature verification fails

Receiving duplicate events

Why does the first subscription payment produce two events?

When exactly does `subscription.canceled` arrive?

Difference between `subscription.canceling` and `subscription.canceled`

What does `data.amount` mean for different events?