App Store Server Notifications

App Store server notifications are how Botsi finds out about events that happen outside your app: refunds, subscription changes, billing problems. Without them, Botsi's view of a subscription only updates when your app tells it something, which drifts further from the truth the longer the subscription runs.

Your App Store server notifications URL is in the Botsi dashboard under App Settings → Apple App Store → App Store server notifications, as URL for App Store server notifications. It has this form:

https://api.botsi.com/v2/notifications/apple/<notification-key>

The dashboard shows the same URL on app.botsi.com, which works the same way. See Notification URLs.

There are three ways to set this up: send directly from Apple, forward from a platform you already use, or forward from your own backend.

Sending directly from Apple#

In App Settings → Apple App Store in the Botsi dashboard, copy the URL for App Store server notifications.
Go to App Store Connect, open your app, and go to General → App Information → App Store Server Notifications.
Choose Edit and paste the URL into both the Production Server URL and the Sandbox Server URL fields.
Select Version 2 notifications and save.

Both fields matter. A sandbox URL left blank means your test purchases never reach Botsi, which looks identical to a broken integration while production works fine.

Botsi accepts Version 2 notifications only. A Version 1 body, which has no signedPayload, is rejected with 400.

Forwarding raw events to your own endpoint#

To keep receiving raw server-to-server events from Apple while using Botsi, add your endpoint to the URL for forwarding raw Apple events field. Botsi forwards those events to your endpoint exactly as they arrived from Apple, unchanged and unmodified.

Forwarding from another platform#

If App Store Server Notifications already route through another platform (RevenueCat, Adapty, or similar), forward those events to Botsi instead of, or in addition to, sending them from Apple. This is the usual setup when an intermediary handles subscriptions or analytics and you still want Botsi to see the full event stream.

In Botsi, copy the URL for App Store server notifications from App Settings → Apple App Store → App Store server notifications.
In the other platform, open its iOS app settings and find the Apple server-to-server notification settings.
Paste the Botsi URL into the field labeled Apple Server Notification Forwarding URL.
Save.

Events forward to Botsi automatically as Apple sends them.

If Superwall or Adapty reports your revenue to Botsi, don't forward App Store notifications to Botsi as well. See Using one revenue platform at a time.

Forwarding from your own backend#

If a custom backend or middleware processes App Store Server Notifications, configure Apple to send events to your system as usual, then forward them to Botsi.

Forward the payload exactly as Apple sent it

Do not modify, decrypt, re-encrypt, or reshape the event. Preserve the full request body, the headers where applicable, and the original JSON structure, then POST it to the Botsi App Store Server Notifications URL.

Botsi verifies and decodes each notification independently using Apple's public keys. A payload that has been touched in transit fails that verification, and the event is discarded rather than partially applied.

How Botsi verifies notifications#

Two checks must pass. The signed payload must verify against Apple's certificate chain, and its bundle ID must equal the iOS Bundle ID saved in Botsi.

A wrong Bundle ID in Botsi fails every notification

A notification whose bundle ID doesn't match is rejected with 400, so Apple keeps retrying it until you correct the Bundle ID in Botsi. See Connect to App Store.

What Botsi records#

Each notification updates the subscriber's status and Access Levels. Botsi also records revenue from it:

Apple notification	Recorded as
Initial purchase (`SUBSCRIBED` with `INITIAL_BUY`)	A paid subscription. A paid introductory offer is a paid trial start, and a free trial is a $0 trial start
Renewal, resubscribe, or upgrade	A renewal. The first full-price charge after a trial is the trial conversion
One-time purchase (`ONE_TIME_CHARGE`)	A one-time purchase
`REFUND`	A refund, as negative revenue
Expiry, failed renewal, renewal-status change, grace-period expiry, refund declined, or consumption request	A $0 status change

Refund reversed, revoke, price increase, renewal extended, summary, and TEST notifications aren't recorded as revenue.

The environment comes from the signed transaction, Production or Sandbox. Family Sharing charges are recorded at $0.

Responses#

Status	When
`200`	The notification was processed. A purchase of a Product that isn't configured in Botsi is also acknowledged with `200`
`400`	The payload doesn't verify, the bundle ID doesn't match, or `signedPayload` is missing
`500`	A temporary failure. Apple retries

The responses every notification URL shares, such as 404 for an unknown notification key, are listed in Notification URLs.