Nuxie/Docs
API Reference

Webhooks

App Store webhook events handled by Nuxie

Webhooks

Nuxie processes webhooks from App Store Connect 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.io/app-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 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.

Error handling and retries

Apple retries webhook deliveries if they do not receive a successful response. See Apple's documentation for details.

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