Nuxie/Docs
API Reference

Webhooks

App Store and Google Play webhook events handled by Nuxie

Webhooks

Nuxie processes webhooks from App Store Connect and Google Play to keep subscription state in sync. Configure webhook URLs in your payment processor settings to enable automatic entitlement updates, subscription tracking, and revenue analytics.

Webhook URLs

Find your webhook URLs in the dashboard under Settings > Apps > [Your App]. Each app has separate URLs for test and live environments:

ProviderURL pattern
App Storehttps://webhooks.nuxie.ai/app-store/{appId}/{env}
Google Playhttps://webhooks.nuxie.ai/play-store/{appId}/{env}

Replace {env} with test or live depending on the environment.

Tip: Configure your test environment webhooks first. Use the App Store sandbox or Google Play license testing to verify everything works before going live.

App Store server notifications

Setup

  1. Open App Store Connect > App > App Information.
  2. Scroll to App Store Server Notifications.
  3. Set the Production Server URL to your live webhook URL.
  4. Set the Sandbox Server URL to your test webhook URL.
  5. Select Version 2 for the notification format.

Notification verification

Nuxie validates App Store server notifications using Apple's signed JWT format. Each notification is verified for:

  • JWT signature validity
  • Environment match (Apple Sandbox maps to Nuxie test, Apple Production maps to Nuxie live)
  • Bundle ID match against your app configuration

Idempotency

Each App Store notification includes a unique notificationUUID. Nuxie uses this to deduplicate notifications. If the same notification arrives twice within 7 days, the duplicate is acknowledged without reprocessing.

Handled notification types

Apple notification typeWhat Nuxie does
SUBSCRIBEDCreates a subscription record and grants entitlements
DID_RENEWExtends the subscription period and maintains entitlements
DID_FAIL_TO_RENEWMarks the subscription as in a billing retry state
DID_CHANGE_SUBSCRIPTIONUpdates the subscription to the new product/plan
EXPIREDMarks the subscription as expired and revokes entitlements
CANCELRecords the cancellation (entitlements remain until period end)
REFUNDProcesses the refund and adjusts entitlements
CONSUMPTION_REQUESTHandles Apple's consumption information request
TESTAcknowledges test notifications (no state changes)

What happens on subscription change

When Nuxie receives an App Store notification:

  1. The notification JWT is verified and decoded.
  2. Nuxie checks for duplicate notifications using the notificationUUID.
  3. The handler updates the user's subscription status, auto-renew state, and expiration dates.
  4. Entitlements are recalculated and available at the edge immediately.
  5. Transaction and notification records are written asynchronously for audit.

Google Play Real-time Developer Notifications

Google Play RTDN messages arrive through a Pub/Sub push subscription pointed at your Nuxie Play Store webhook URL.

Setup

Follow the full Google Play integration guide to configure the Developer API service account, Pub/Sub topic, push subscription, and Play Console RTDN topic.

Notification verification

Nuxie verifies Google Play RTDN using:

  • Package name match against your app configuration
  • Pub/Sub OpenID Connect JWT email and audience when a Pub/Sub service account email is configured
  • Optional shared verification token through the token query parameter

Idempotency

Nuxie uses the Pub/Sub messageId when available. If a raw developer notification is processed without a Pub/Sub envelope, Nuxie derives a stable notification ID from the package name, event time, payload kind, notification type, and purchase token or order ID.

Webhook ingress claims the provider event before queueing work. The queue handler marks the event processed only after purchase fulfillment, provider notification logging, and billing event fanout succeed.

Handled notification types

Google Play notification familyWhat Nuxie does
Subscription notificationsFetches purchases.subscriptionsv2, updates lifecycle state, and syncs entitlements
One-time product notificationsFetches purchases.productsv2, records purchase or cancellation, and grants or withholds entitlements
Voided purchase notificationsRecords refunds/revocations and updates customer products, including quantity-based partial refunds
Test notificationsAcknowledges the test event without changing purchase state

For Google Play cancellation events, customer webhook payloads include cancellationReason, cancelSurveyReason, and cancelSurveyReasonUserInput when Google returns that context from purchases.subscriptionsv2. Pending subscription or one-time purchase cancellations are delivered as pending_purchase_canceled so they do not look like an active entitlement cancellation. Billing retry webhooks can include billingIssueReason and billingIssuePendingOrderId for renewal-declined account hold or grace-period states. Price step-up RTDNs are delivered as price_increase_consent with the recurring price, price-change state, consent deadline, and new price when Google returns them. Google Play refund webhooks include refundType, refundReason, refundSource, refundAmount, refundCurrency, refundTaxAmount, refundedQuantity, and remainingQuantity when the voided purchase payload or hydrated transaction contains that context.

Error handling and retries

Apple and Google Pub/Sub retry webhook deliveries if they do not receive a successful response. See Apple's documentation and Google Pub/Sub push subscriptions for provider-specific retry behavior.

Nuxie returns a success response (200) as quickly as possible. Durable writes (transaction records, notification logs) are processed asynchronously after the response is sent, so webhook timeouts are rare.

If Nuxie cannot load your app's edge configuration when a webhook arrives, it returns a 503 error. The payment provider retries automatically. This can happen briefly after initial setup before your configuration has propagated.

Next steps