App Store Server-Benachrichtigungen V2 in 2026
Apple hat den Weg über Version 1 geschlossen: Benachrichtigungen der Version 1 und der App Store Receipts-Endpunkt sind veraltet, und die Anweisung lautet nun „implementieren Sie den Endpunkt der Version 2 auf Ihrem Server“. Für eine App mit laufenden Abos ist das keine kosmetische Migration – über den Benachrichtigungsstrom erfährt Ihr Server, dass eine Verlängerung erfolgreich war, dass eine Rückerstattung ausgezahlt wurde, dass die Abrechnung erneut versucht wird oder dass Apple Sie auffordert, eine Rückerstattungsanfrage zu begründen. Dieses Tutorial zeigt das vollständige Setup für 2026: Version 2 in App Store Connect aktivieren, das JWS verifizieren, jeden Benachrichtigungstyp und -subtyp zuordnen und die App Store Server API für den Zustand nutzen, den eine Benachrichtigung nur zu einem bestimmten Zeitpunkt beschreibt.
Die Ein-Satz-Version: App Store Connect sendet ein JWS-signiertes JSON-Objekt per POST an Ihre HTTPS-URL; prüfen Sie die Signaturkette, dekodieren Sie signedPayload, reagieren Sie auf notificationType plus subtype, antworten Sie schnell mit 200-206 und rufen Sie die App Store Server API auf, wann immer Sie den aktuellen Zustand statt des Ereigniszustands benötigen.
Schritt 1 – Korrigieren Sie die beiden Endpunkte, bevor Sie App Store Connect anfassen
You need one HTTPS URL for production and, optionally, a second one for sandbox; Apple explicitly allows you to use the same URL for both environments. Your server must support TLS 1.2 or later. If the URL contains a port, it must be either 443 or 1024 and above — https://example.com:1234/notifications is a valid shape, a low privileged port is not. And if your edge terminates behind an IP allow list, add Apple's 17.0.0.0/8 subnet, which applies to sandbox and production alike. All of this is documented in Enabling App Store Server Notifications.
Schritt 2 — Version 2 pro Umgebung aktivieren
Öffnen Sie in App Store Connect Ihre App und gehen Sie dann zu App-Informationen > App Store Server-Benachrichtigungen. Produktion und Sandbox werden getrennt konfiguriert, und jede Umgebung wählt unabhängig Version 2 oder die veraltete Version 1 – so können Sie das neue Format in der Produktion nutzen, während das alte anderswo noch funktionieren muss, oder umgekehrt. Der von Apple vorgegebene Migrationspfad lautet: Testen Sie Version 2 zuerst in der Sandbox-Umgebung und stellen Sie erst danach die Produktion um. Ein Verhalten, das Sie vor dem Debuggen kennen sollten: Die Benachrichtigung TEST wird immer im Format von Version 2 gesendet, unabhängig davon, welche Version Ihre konfigurierte URL erwartet.
Schritt 3 — Antworten Sie mit dem richtigen Statuscode und arbeiten Sie dann asynchron
Antworten Sie mit einem HTTP-Statuscode von 200-206, wenn der POST erfolgreich verarbeitet wurde. Wurde er nicht verarbeitet, senden Sie einen 50x oder 40x, damit App Store die Benachrichtigung erneut versucht. Das praktische Muster lautet: Body lesen, verifizieren, in die Warteschlange einreihen, mit 200 antworten und die eigentliche Arbeit in einem Worker erledigen. Halten Sie die Verbindung nicht offen, während Sie Ihre eigene Datenbank, Ihren E-Mail-Anbieter oder die App Store Server API aufrufen. Wiederholungsversuche schützen Sie vor Infrastrukturausfällen, nicht vor einem langsamen Handler — und jeder ausgelöste Wiederholungsversuch ist ein doppeltes Event, das Sie anschließend unterdrücken müssen.
Schritt 4 — Payload entschlüsseln
Der Body ist ein responseBodyV2-Objekt, dessen einzig relevantes Feld signedPayload ist, ein JWS. Zerlegen Sie es in seine Header-, Payload- und Signatur-Repräsentationen und dekodieren Sie die Payload dann per Base64URL, um die responseBodyV2DecodedPayload zu erhalten. Auf dieser Ebene erhalten Sie notificationType, subtype, version, signedDate und notificationUUID. Genau eines von vier Datenobjekten ist vorhanden: data für In-App-Kauf-Ereignisse mit einer signedTransactionInfo und – bei automatisch verlängerbaren Abos – einer signedRenewalInfo; summary, das nur bei einer RENEWAL_EXTENSION mit dem Subtyp SUMMARY erscheint; appData; oder externalPurchaseToken, das nur bei einer EXTERNAL_PURCHASE_TOKEN-Benachrichtigung erscheint.
Schritt 5 — Prüfen Sie jede Signatur, nicht nur die äußere
Alle drei signierten Repräsentationen – signedPayload, signedTransactionInfo und signedRenewalInfo – tragen ihre eigene JWS-Signatur, und jede muss validiert werden; verwenden Sie den Algorithmus, der im alg-Parameter des Headers genannt wird. In der Praxis bedeutet das, die x5c-Zertifikatskette bis zum veröffentlichten Root von Apple zu prüfen, den Sie von der Apple-Zertifizierungsstellen-Seite herunterladen (das aktuelle Root für diesen Dienst ist AppleRootCA-G3.cer). Bauen Sie das nicht selbst: Apple veröffentlicht die App Store Server Library für Python, Java, Node.js und Swift, die die Verifizierung und das Dekodieren für Sie übernimmt. Ein Handler, der die Payload Base64-dekodiert und die Verifizierung überspringt, ist trivial fälschbar – jeder, der Ihre Benachrichtigungs-URL kennt, kann sich selbst ein Abo gewähren.
Schritt 6 — Ordnen Sie notificationType und Subtyp Ihren Berechtigungen zu
Die Enum-Version 2 definiert 23 Benachrichtigungstypen und 19 Subtypen, die einige davon näher bestimmen; beide Listen sind unter notificationType und subtype veröffentlicht. Diejenigen, die entscheiden, ob ein zahlender Kunde den Zugang behält:
SUBSCRIBED— mit den UntertypenINITIAL_BUY,RESUBSCRIBE,UPGRADEundDOWNGRADE. Gewähren Sie Zugriff und erfassen Sie die Produkt-ID, nicht nur „subscribed".DID_RENEW— mit den UntertypenBILLING_RECOVERYundBILLING_RETRY. Eine Verlängerung, die nach einem Zahlungsproblem eingegangen ist, kommt weiterhin hier an, behandeln Sie sie daher als normale Verlängerung des Zugangs.DID_FAIL_TO_RENEW— mit dem SubtypGRACE_PERIOD, wenn sich der Kunde innerhalb einer Karenzzeit befindet. Der Zugriff läuft hier in der Regel weiter, und genau das ist der Sinn von Karenzzeiten.GRACE_PERIOD_EXPIRED— die Karenzzeit ist abgelaufen. Dies ist der Punkt zum Downgrade, nicht erst bei der fehlgeschlagenen Abbuchung.EXPIRED– mit den UntertypenVOLUNTARY,BILLING_RETRYundPRODUCT_NOT_FOR_SALE. Der letzte ist relevant, wenn Sie ein Produkt aus dem Verkauf nehmen, während es noch von Nutzern gehalten wird.DID_CHANGE_RENEWAL_STATUS(AUTO_RENEW_ENABLED/AUTO_RENEW_DISABLED) undDID_CHANGE_RENEWAL_PREF(UPGRADE/DOWNGRADE) – ein Kunde, der die automatische Verlängerung deaktiviert hat, hat bis zum Ende des Zeitraums weiterhin Anspruch, entziehen Sie also niemals beiAUTO_RENEW_DISABLEDden Zugang.REFUND,REFUND_DECLINED,REFUND_REVERSED,REVOKEundRESCIND_CONSENT– die Widerrufsseite. Eine rückgängig gemachte Erstattung bedeutet, dass das Geld zu Ihnen zurückkam, also muss die Berechtigung auch zum Kunden zurückkommen.CONSUMPTION_REQUEST— Apple fordert Belege darüber an, wie der Kauf genutzt wurde; siehe Schritt 7.OFFER_REDEEMED,PRICE_CHANGE,PRICE_INCREASE(ACCEPTED/PENDING),RENEWAL_EXTENDEDundRENEWAL_EXTENSION(SUMMARY/FAILURE) – kommerzielle Änderungen und Datumsänderungen, die in der Regel eine Kundenbenachrichtigung erfordern statt einer Änderung des Zugriffs.METADATA_UPDATE,MIGRATION,ONE_TIME_CHARGE,TESTundEXTERNAL_PURCHASE_TOKEN(mit dem SubtypUNREPORTED, wenn Apple ein Token generiert hat, für das kein Bericht vorliegt).
Der vollständige Katalog mit den aktuellen Ergänzungen findet sich im Änderungsprotokoll der Benachrichtigungen — Apple ergänzt im Laufe der Zeit Felder und Werte, lesen Sie es daher erneut, bevor Sie davon ausgehen, dass Ihr Handler vollständig ist.
Schritt 7 — Beantworten Sie eine CONSUMPTION_REQUEST innerhalb von 12 Stunden
Wenn ein Kunde für einen Produkttyp eine Rückerstattung anfordert – ob Verbrauchsartikel, Nicht-Verbrauchsartikel, nicht erneuernd oder automatisch erneuernd –, sendet Apple eine CONSUMPTION_REQUEST. Hat der Kunde eingewilligt, können Sie mit Send Consumption Information antworten und die von Apple verlangten Nutzungsdaten übermitteln; Apple dokumentiert ein 12-Stunden-Antwortfenster ab Eingang der Benachrichtigung. Hat der Kunde nicht eingewilligt, antworten Sie gar nicht. Zwei Regeln werden leicht verwechselt: Die für diese API benötigte Einwilligung ist getrennt von der Einwilligung, die Sie für Tracking oder Werbung eingeholt haben, und Sie sind die Partei, die vor der Weitergabe von Nutzungsdaten an Apple eine gültige Einwilligung einholen muss.
Schritt 8 – Nutzen Sie die App Store Server API für den Status, nicht für das Ereignis
Eine Benachrichtigung beschreibt einen Moment. Bevor Sie Ansprüche formulieren, klären Sie die Gegenwart:
- Transaktionsinformationen abrufen für eine einzelne Transaktion, einschließlich ihres Widerrufsgrunds und -datums.
- Get All Subscription Statuses für die maßgebliche Ansicht der Abos eines Kunden.
- Erstattungsverlauf abrufen, wenn Sie die Erstattungen für eine ursprüngliche Transaktions-ID benötigen.
- Verlängern eines Abo-Verlängerungsdatums als Ausgleich für eine Dienststörung. Zwei Eigenschaften machen daraus eine Einbahnstraße: Nachdem die Verlängerung wirksam geworden ist, gibt es keine Möglichkeit, sie rückgängig zu machen, und die Abos von Familienmitgliedern werden automatisch verlängert, während direkte Anfragen für das Abo eines Familienmitglieds nicht unterstützt werden. Der Verlängerungszeitraum zählt außerdem nicht zu dem einen Jahr bezahlten Dienstes, das Apple bei der Berechnung der Provisionsrate zugrunde legt.
Schritt 9 — Belegen Sie, dass die Pipeline funktioniert, bevor Sie sich darauf verlassen
Call Request a Test Notification and the App Store sends a TEST notification to your endpoint. That call returns a token you pass to Get Test Notification Status within six months to see how your server actually answered. Separately, if your endpoint was down at 3am, Get Notification History returns the version 2 notifications the App Store attempted to send: 180 days in production, 30 days in the sandbox, 20 records per page with a continuation token, and full notification contents. Remember what that history is: each record reflects the state at the time the notification was originally sent, not the current state.
Schritt 10 — Die operativen Regeln, die die Pipeline korrekt halten
- Lesen Sie
environment, bevor Sie etwas schreiben. Sandbox-Traffic erreicht Sandbox-URLs; wenn ein gemeinsam genutzter Handler aus einem Sandbox-Event Produktions-Berechtigungen schreibt, wird aus dem Test ein Datenvorfall. - Deduplizieren Sie über
notificationUUID. Wiederholungen und Ihre eigene erneute Verarbeitung erzeugen dasselbe Ereignis mehrfach; speichern Sie die Kennung und verwerfen Sie Duplikate. - Behandeln Sie eine Benachrichtigung niemals als Beleg. Ein Build, der nur auf
SUBSCRIBEDundDID_RENEWhört undREFUND,REVOKEundREFUND_REVERSEDignoriert, lässt bezahlten Zugriff dauerhaft durchsickern. Behandeln Sie den gesamten Lebenszyklus oder übergeben Sie die Verifizierung an die Bibliothek von Apple und fragen Sie die Server-API. - Führen Sie ein eigenes Ereignisprotokoll. Wenn ein Kunde den Zugriff bestreitet, sind der Benachrichtigungsverlauf und Ihr eigenes Protokoll das, womit Sie die Entscheidung rekonstruieren können.
- Planen Sie den Endpunkt als Teil der Produktion ein. Er braucht Monitoring, ein Request-Timeout weit unter dem Verbindungsbudget und eine Queue – keine synchrone Aufrufkette in Ihr Abrechnungssystem.
Quellen
- Apple-Entwickler — App Store-Server-Benachrichtigungen: developer.apple.com/documentation/appstoreservernotifications
- Apple Developer – App Store Server Notifications V2: app-store-server-notifications-v2
- Apple-Entwickler — App Store-Server-Benachrichtigungen aktivieren: enabling-app-store-server-notifications
- Apple Developer — notificationType- und subtype-Enums: notificationtype / subtype
- Apple Entwickler – responseBodyV2DecodedPayload: responsebodyv2decodedpayload
- Apple Developer – App Store Server API: developer.apple.com/documentation/appstoreserverapi
- Apple – App Store Server Library (Python): github.com/apple/app-store-server-library-python
- Apple — Zertifizierungsstelle: www.apple.com/certificateauthority
Sie verwalten Entwicklerkonten im großen Stil? Wir übernehmen die operative Seite.
Wir haben Ihre Nachricht erhalten und antworten innerhalb von 24 Stunden.
← Zurück zum Bearbeiten