Setup guide
Connect your app to Salebell
Salebell receives Apple's App Store Server Notifications (version 2) for your app. There is no SDK and nothing changes in your app. Import from App Store Connect and let Salebell configure the URLs, or enter your app and paste the URLs manually.
Self-host Salebell or use optional managed cloud. Install your own instance before connecting an app. Android / Google Play RTDN: Preview. For Android, upload a service-account JSON key, select an app, configure Pub/Sub and send a test from Play Console. App discovery requires the Google Play Developer Reporting API and app access in Play Console; manual entry is also available. Purchase and renewal prices come from verified Google orders, including discounts and tax. Refunds deduct only the newly refunded amount.
What's covered: in-app purchases and subscriptions, meaning purchases, free trials, renewals, refunds, billing issues, cancellations and expirations. Apple doesn't send server notifications for paid-app downloads, so those don't appear in Salebell.
Before you start
- For automatic setup: an App Store Connect team API key with App Manager access, its Key ID and Issuer ID. This key imports apps and configures notification URLs; it is different from an In-App Purchase test key.
- For manual setup: your app's bundle ID, for example
com.example.myapp. Salebell only accepts notifications whose signed payload carries this bundle ID. - An App Store Connect role that can edit server URLs: Account Holder, Admin, App Manager or Marketing.
- Optional: your app's Apple ID, the number under General → App Information in App Store Connect. When set, production notifications must match it too.
1. Add your app
- Sign in. Cloud sends a 6-digit email code. Self-hosted instances use an administrator-created account and password.
- Click Add app. Apple App Store is selected by default; Android opens the Google Play setup flow.
- Save or select an App Store Connect team key, choose the app, and review the connection. Choose Enter app details manually if you prefer to enter the name, bundle ID and optional Apple ID without a key.
- Salebell shows two URLs, one per environment. Each contains a random key that identifies your app:
https://salebell.vercel.app/hooks/apple/<your-key>/production https://salebell.vercel.app/hooks/apple/<your-key>/sandbox
2. Keep your existing server (before you paste)
App Store Connect accepts one URL per environment. If one of those fields already points at your own server (or another service), automatic setup preserves supported existing Version 2 URLs. Review them under Connection details. With manual setup, copy them before replacing them, then save them under Your server in Salebell.
- Every notification that passes verification is forwarded with the same body Apple sent (the
signedPayloadJSON), so your server keeps verifying Apple's signature exactly as before. - Production notifications go to the production forwarding URL and sandbox notifications to the sandbox one.
- Forwarding happens in the background after Salebell acknowledges Apple. It's one attempt with a 10-second timeout, and failures are logged. To backfill anything your server missed, use Apple's Get Notification History endpoint.
- Forwarded requests keep Apple's content type and add one header,
x-salebell-forwarded: 1. Redirects aren't followed, so use your server's final URL. - Forwarding URLs must use https and a public host name (no IP addresses or localhost). Forwarding is on every plan.
3. Connect Apple notifications
With automatic setup, select Start receiving notifications. Salebell checks Apple's current settings, preserves supported existing servers through forwarding, and configures both URLs for Version 2. If a Version 1 or unsupported receiver needs attention, review the error and continue manually.
Manual setup
Already have a URL in either App Store Connect field? Copy it into Your server first, or your server stops receiving notifications.
These are Apple's steps for setting a server URL. Do it once for production and once for sandbox.
Production
- In Apps, select your app.
- In the sidebar, under General, click App Information.
- Scroll down to General Information, then go to App Store Server Notifications.
- Under Production Server URL, click Set Up URL (or Edit if a URL is already there).
- Paste your Salebell production URL.
- Choose Version 2. Salebell doesn't accept version 1, which Apple has deprecated.
- Click Save.
Sandbox
Repeat the same steps under Sandbox Server URL with your Salebell sandbox URL, Version 2.
Set both. If the Sandbox Server URL is empty, Apple sends sandbox notifications to the production URL, and Salebell rejects them there because the signed environment doesn't match the URL. Apple notes that changes can take up to an hour to reach the sandbox environment.
4. Check your connection
Your app's setup page in Salebell shows Waiting for the first notification… and switches to Connected as soon as anything arrives. There are two ways to trigger one.
Option A: make a sandbox purchase
Buy something in a TestFlight build, or in a development build while signed in with a Sandbox Apple Account (create one in App Store Connect under Users and Access → Sandbox). Apple sends the notification to your sandbox URL and it appears in Salebell with a Sandbox label.
Purchases made with StoreKit Testing in Xcode (a local .storekit configuration file) never reach Apple's servers, so they don't produce server notifications.
Option B: ask Apple for a TEST notification
No purchase needed. Under Check your connection on your app's Setup page, use Send an App Store test notification. Pick Sandbox or Production, select a saved In-App Purchase key or upload one, then click Send sandbox test notification or Send production test notification. An accepted request may still be pending or fail delivery. When Salebell receives and verifies it, the event feed shows Test notification. The test form stays visible after receipt.
To get the key, open App Store Connect → Users and Access → Integrations → In-App Purchase → Generate In-App Purchase Key (Account Holder or Admin) and download the .p8 file. Copy the Key ID (filled in for you when the file name has it) and the Issuer ID from the top of that page. Salebell reuses the Issuer ID for a known key or single saved Apple team; choose the matching team when several are saved. Owners and admins can save the key encrypted for reuse or choose one-time use without saving. An App Store Connect API key imports apps and configures their URLs; it cannot send this test.
5. Set up alerts (optional)
Salebell records verified notifications without an alert destination. Choose Set up alerts (optional) → when you want alerts, or go straight to the dashboard. From alert setup, ← Connection & test returns to the Apple test.
- iPhone: when a compatible shared-app distribution is available, install it, open Settings → Server, choose Salebell or enter your instance's HTTPS website/API URLs and public key, then sign in and allow notifications. Customer operators do not need APNs keys or another app publication. Push uses the managed relay and reaches enabled devices of current workspace members. Sandbox alerts are off by default and can be turned on per device. Get the Salebell iPhone app
- Integrations: on your app's Integrations tab, add Slack or Discord (incoming webhook URL), Telegram (bot token and chat ID), Pushover (app token and user key), PostHog (project API key and host) or your own webhook (URL and signing secret). Each one has a Send test alert button.
- Phone-style channels (Telegram, Pushover) get money and churn events by default. Webhooks and PostHog get every event.
The shared app and relay are implemented in the repository; publication and live relay verification remain operator tasks. One backend/user is active per phone. Sign-out and switching wait for central revocation; if the relay is unavailable, retry after connectivity returns. Dashboard access and other alert channels continue independently. iPhone connection details.
Webhook format
Webhook integrations receive a JSON POST for each event with two headers you can use to verify it came from Salebell:
x-salebell-timestamp: 1791504000
x-salebell-signature: hex(HMAC-SHA256(secret, "<timestamp>.<raw body>"))
{
"type": "store_event",
"app": "My App",
"event": {
"id": "…", "store": "app_store", "environment": "Production",
"type": "purchase", "rawType": "SUBSCRIBED", "rawSubtype": "INITIAL_BUY",
"occurredAt": "2026-10-09T08:41:00.000Z",
"productId": "pro.yearly", "revenue": 49.99, "currency": "USD", "storefront": "USA",
"transactionId": "…", "originalTransactionId": "…", "appUserId": null,
"isTrial": false, "isFamilyShared": false
}
}Compute the HMAC over the timestamp, a dot and the raw request body, compare it in constant time and reject old timestamps. Refunds carry a negative revenue.
Troubleshooting
- Nothing arrives. Check that the URL in App Store Connect matches exactly, that Version 2 is selected and that the app is enabled in Salebell. Apple can take up to an hour to apply changes in sandbox.
- Production works, sandbox doesn't. Make sure the Sandbox Server URL is set to the URL ending in
/sandbox. - Notifications are rejected. The bundle ID in Salebell must match the app exactly. If you entered an Apple ID, it must match the app too.
- My own server stopped receiving notifications. Add its URL under Your server for the matching environment.
Still stuck? Your app's dashboard shows every notification Salebell accepted. If the feed stays empty after a sandbox purchase, Apple didn't deliver it to Salebell, and the Get Test Notification Status endpoint will tell you why.