Skip to main content
app.* events tell your app about its own App Store billing and about priced actions fans buy inside its experiences. They reach your app only, and you can’t subscribe to them through POST /webhooks/subscriptions. You need read:self on your app, a destination in the Events tab or your App Manifest, and a receiver that verifies X-Fanvue-Signature against the raw body before it parses JSON.

​
Available events

app.payment.* events cover one-time purchases and subscription charges alike, so branch on billing_reason to tell them apart. app.subscription.deactivated is reserved and never emitted.

​
Setup and delivery

App events go to your app’s own destinations, never to a creator’s. Register them in the Events tab or in webhooks.destinations of your App Manifest; see Subscribe to webhooks.

​
Event envelope

Every app event arrives in the shared envelope. Here is an app.payment.succeeded delivery:
id is a hash of your app, the event’s own identifier and the topic, so it is stable across retries. On app.subscription.* the hash covers the subscription and the topic rather than the occurrence; see Repeated subscription state transitions. data.object is one of payment, subscription, refund, dispute, experience_action_payment, experience_action_refund or experience_action_dispute.

​
Amounts and currency

Amounts are integers in USD cents, so 999 means $9.99; Units and currency covers fees and settlement. currency is always "USD" on every app payment, refund and experience-action event. Dispute resources are the exception: they carry the processor’s currency, which can be null.

​
Money and access are separate events

A subscription’s initial charge emits both app.payment.succeeded with billing_reason: "subscription_initial" and app.subscription.activated. Fulfil access from the subscription event and reconcile revenue from the payment event.
app.refund.created, app.payment.refunded and app.dispute.* cover one-time purchases only, identified by a purchase_reference with the appotp_ prefix. Subscription reversals and chargebacks are reconciled through GET /apps/{appUuid}/subscription-status, not these events.

​
Attribution

metadata on every app resource echoes the client_metadata captured with the purchase, as an object of string keys and values, and is {} when none was set. client_reference_id is captured for one-time item purchases when you append it to the item’s checkout link, and it is echoed on the related app.payment.* and refund events. It is null on subscription charges and when not provided. See One-time items.

​
Reconciliation

Webhooks can be missed or delayed, so reconcile against the REST endpoints. The app payment endpoints are read-only and require read:self. They split into owner-scoped and caller-scoped reads. invoiceNumber matches data.id on a payment or data.payment_id on a refund. For subscription state use GET /apps/{appUuid}/subscription-status; for action purchases use GET /experiences/{uuid}/action-purchases. All of these appear under Apps and Experiences in the API reference.