stubkit docs

Webhook setup

Apple App Store Server Notifications v2

Apple delivers subscription lifecycle events as signed JWS payloads via App Store Server Notifications (ASSN) version 2. stubkit verifies the signature against Apple's certificate chain and applies the event to your tenant's canonical state.

Endpoint to paste

https://api.stubkit.com/v1/webhooks/apple

One endpoint across all tenants. The bundle ID inside the payload routes to the right tenant automatically.

Setup steps

Full credential walkthrough (including the two separate Apple key types) is in the Integrations guide. Short version:

  1. In App Store Connect → Users and Access → Integrations → In-App Purchase tab, generate an API key. Download SubscriptionKey_*.p8, copy its Key ID, copy the team-level Issuer ID.
  2. In app.stubkit.com → Integrations → Add Apple. Paste issuer ID, IAP key ID, .p8 contents. Save.
  3. In app.stubkit.com → your app → Settings → Apple section, pick the connection from the dropdown. Fill in the bundle ID.
  4. Back in App Store Connect → My Apps → your app → App Information → App Store Server Notifications, set the Production Server URL to https://api.stubkit.com/v1/webhooks/apple and Version to v2.
  5. Keep the Sandbox Server URL pointing at your staging stubkit instance until the cut-over is complete.

For product catalog sync (prices, subscription groups), you also need a separate App Store Connect API key with App Manager role — covered in the Integrations guide.

What we verify

  • The JWS is signed with ES256 using the leaf certificate in the x5c header.
  • The certificate chain anchors to Apple's trusted root authority by pinned fingerprint.
  • Optional cross-check with the App Store Server API provides a second authoritative trust anchor on top of the JWS signature.

What we store

The full raw body is archived under apple/<bundleId>/yyyy/mm/dd/<notificationUUID>.json with a two-year retention policy. A normalized message is dispatched for asynchronous processing and the per-user state engine updates canonical state before any subsequent read returns.