2026년 App Store 서버 알림 V2
Apple가 버전 1 경로를 종료했습니다. 버전 1 알림과 App Store Receipts 엔드포인트가 지원 종료되었으며, 이제 안내 문구는 "서버에 버전 2 엔드포인트를 구현하세요"로 바뀌었습니다. 라이브 구독이 있는 앱에게 이는 겉치레용 이관이 아닙니다. 알림 스트림은 서버가 갱신 성공, 환불 발생, 결제 재시도, 또는 Apple가 환불 요청에 대한 소명을 요구하는 상황을 인지하는 경로이기 때문입니다. 이 튜토리얼은 App Store Connect에서 버전 2를 활성화하고, JWS를 검증하고, 모든 알림 유형과 하위 유형을 매핑하고, 알림이 특정 시점의 상태만 설명하는 부분에 대해 App Store Server API를 활용하는 2026년 전체 설정 과정을 다룹니다.
한 줄 요약: App Store Connect가 JWS 서명된 JSON 블롭을 HTTPS URL로 POST하면, 서명 체인을 검증하고 signedPayload를 디코딩한 뒤 notificationType과 subtype에 따라 처리하고, 200-206으로 신속히 응답하며, 이벤트 상태가 아닌 현재 상태가 필요할 때마다 App Store Server API를 호출하세요.
1단계 — App Store Connect를 건드리기 전에 두 엔드포인트를 수정하세요
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.
2단계 — 환경별로 버전 2 활성화하기
App Store Connect에서 앱을 연 다음 앱 정보 > App Store 서버 알림으로 이동하세요. 프로덕션과 샌드박스는 별도로 설정되며, 각 환경에서 버전 2 또는 지원 종료된 버전 1을 독립적으로 선택할 수 있습니다. 덕분에 프로덕션에서는 새 형식을 운영하면서 다른 환경에서는 여전히 구버전이 작동해야 하는 상황, 또는 그 반대 상황을 처리할 수 있습니다. Apple이 제시하는 이관 경로는 먼저 샌드박스 환경에서 버전 2를 테스트한 뒤에만 프로덕션으로 옮기는 것입니다. 디버깅을 시작하기 전에 알아둘 동작이 하나 있습니다. TEST 알림은 설정된 URL이 어느 버전을 기대하든 항상 버전 2 형식으로 전송됩니다.
3단계 — 올바른 상태 코드로 응답한 뒤 비동기적으로 처리하세요
POST가 성공적으로 처리되면 200-206 HTTP 상태 코드로 응답하세요. 처리되지 않았다면 50x 또는 40x를 보내 App Store가 알림을 재시도하도록 하세요. 실무 패턴은 다음과 같습니다. 본문을 읽고, 검증하고, 큐에 넣고, 200으로 응답한 뒤 실제 작업은 워커에서 수행하세요. 자체 데이터베이스, 이메일 제공업체, App Store Server API를 호출하는 동안 연결을 열어 두지 마세요. 재시도는 인프라 장애로부터 보호하기 위한 것이지 느린 핸들러로부터 보호하기 위한 것이 아니며, 트리거하는 모든 재시도는 이후에 억제해야 하는 중복 이벤트입니다.
4단계 — 페이로드 해독
본문은 responseBodyV2 객체이며, 의미 있는 필드는 JWS인 signedPayload 하나뿐입니다. 이를 헤더, 페이로드, 서명 표현으로 파싱한 다음 페이로드를 Base64URL 디코딩해 responseBodyV2DecodedPayload를 얻습니다. 이 단계에서 notificationType, subtype, version, signedDate, notificationUUID를 확인할 수 있습니다. 네 가지 데이터 객체 중 정확히 하나만 존재합니다. 인앱 결제 이벤트의 경우 data이며 signedTransactionInfo를 담고, 자동 갱신 구독의 경우 signedRenewalInfo도 함께 담습니다. summary는 SUMMARY 서브타입의 RENEWAL_EXTENSION에만 나타납니다. appData, 또는 EXTERNAL_PURCHASE_TOKEN 알림에만 나타나는 externalPurchaseToken도 있습니다.
5단계 — 바깥 서명만이 아니라 모든 서명을 검증하세요
세 가지 서명된 표현인 signedPayload, signedTransactionInfo, signedRenewalInfo는 각각 자체 JWS 서명을 가지며, 모두 검증해야 합니다. 헤더의 alg 파라미터에 명시된 알고리즘을 사용하세요. 실제로는 Apple이 공개한 루트까지 x5c 인증서 체인을 확인하는 것을 의미하며, 이 루트는 Apple 인증 기관 페이지에서 내려받습니다(이 서비스의 현재 루트는 AppleRootCA-G3.cer입니다). 직접 구현하지 마세요. Apple는 Python, Java, Node.js, Swift용 App Store 서버 라이브러리를 제공하며, 이 라이브러리가 검증과 디코딩을 대신 처리합니다. 페이로드를 Base64로 디코딩만 하고 검증을 건너뛰는 핸들러는 손쉽게 위조될 수 있습니다. 알림 URL을 알게 된 사람이라면 누구나 스스로 구독을 부여할 수 있습니다.
6단계 — notificationType과 subtype을 권한에 매핑하기
버전 2 열거형은 23가지 알림 유형과 이 중 일부를 세분화하는 19가지 하위 유형을 정의하며, 두 목록은 notificationType과 subtype에 공개되어 있습니다. 유료 고객의 접근 권한 유지 여부를 결정하는 항목은 다음과 같습니다.
SUBSCRIBED— 하위 유형은INITIAL_BUY,RESUBSCRIBE,UPGRADE,DOWNGRADE입니다. 단순히 "구독됨"으로 처리하지 말고 접근 권한을 부여하고 상품 식별자를 기록하세요.DID_RENEW— 하위 유형은BILLING_RECOVERY와BILLING_RETRY입니다. 결제 문제 이후 도착한 갱신도 여기로 오므로 정상적인 접근 연장으로 처리하세요.DID_FAIL_TO_RENEW— 고객이 유예 기간 내에 있을 때는GRACE_PERIOD하위 유형이 함께 표시됩니다. 이 경우 보통 이용이 계속되는데, 바로 그것이 유예 기간의 존재 이유입니다.GRACE_PERIOD_EXPIRED— 유예 기간이 끝났습니다. 결제 실패 시점이 아니라 이 시점에 다운그레이드해야 합니다.EXPIRED— 하위 유형으로VOLUNTARY,BILLING_RETRY,PRODUCT_NOT_FOR_SALE이 있습니다. 마지막 유형은 이용자가 여전히 상품을 보유한 상태에서 판매를 중단할 때 중요합니다.DID_CHANGE_RENEWAL_STATUS(AUTO_RENEW_ENABLED/AUTO_RENEW_DISABLED) 및DID_CHANGE_RENEWAL_PREF(UPGRADE/DOWNGRADE) — 자동 갱신을 끈 고객도 기간이 끝날 때까지는 이용 권한이 있으므로,AUTO_RENEW_DISABLED에서 절대 권한을 회수하지 마세요.REFUND,REFUND_DECLINED,REFUND_REVERSED,REVOKE,RESCIND_CONSENT— 권한 회수 측면입니다. 환불이 반전되었다는 것은 금액이 다시 들어왔다는 뜻이므로, 이용 권한도 고객에게 돌아가야 합니다.CONSUMPTION_REQUEST— Apple이(가) 구매가 어떻게 사용되었는지에 대한 증빙을 요청하고 있습니다. 7단계를 참고하세요.OFFER_REDEEMED,PRICE_CHANGE,PRICE_INCREASE(ACCEPTED/PENDING),RENEWAL_EXTENDED,RENEWAL_EXTENSION(SUMMARY/FAILURE) — 대개 접근 권한 변경이 아니라 고객 알림이 필요한 상업적·날짜 변경입니다.METADATA_UPDATE,MIGRATION,ONE_TIME_CHARGE,TEST, 그리고EXTERNAL_PURCHASE_TOKEN(Apple가 토큰을 생성했지만 보고할 내역이 없을 때는UNREPORTED하위 유형 포함)입니다.
현재 추가된 항목까지 반영된 전체 목록은 알림 변경 로그에서 확인할 수 있습니다. Apple는 시간이 지나면서 필드와 값이 계속 추가되므로, 핸들러가 완성됐다고 판단하기 전에 다시 읽어 보세요.
7단계 — 12시간 이내에 CONSUMPTION_REQUEST에 응답하기
소비성, 비소비성, 비갱신형, 자동 갱신형 등 어떤 제품 유형이든 고객이 환불을 요청하면 Apple는 CONSUMPTION_REQUEST를 전송합니다. 고객이 동의한 경우 Apple이 요구하는 사용 데이터와 함께 Send Consumption Information을 호출해 응답할 수 있으며, Apple은 알림이 도착한 시점부터 12시간의 응답 기간을 문서화하고 있습니다. 고객이 동의하지 않은 경우에는 응답하지 않습니다. 놓치기 쉬운 두 가지 규칙이 있습니다. 이 API에 필요한 동의는 추적이나 광고를 위해 수집한 동의와 별개이며, Apple와 사용 데이터를 공유하기 전에 유효한 동의를 확보할 책임은 개발자에게 있습니다.
8단계 — 이벤트가 아닌 상태에는 App Store 서버 API를 사용하세요
알림은 한순간을 설명합니다. 권한을 작성하기 전에 현재 상황을 먼저 파악하세요:
- 거래 정보 가져오기 — 취소 사유와 날짜를 포함한 단일 거래 정보.
- 고객 구독의 권위 있는 조회를 위해 모든 구독 상태 조회를 사용하세요.
- 원본 거래 식별자에 대한 환불 내역이 필요할 때 환불 내역 가져오기를 사용하세요.
- 구독 갱신일 연장은 서비스 장애를 보상하기 위한 기능입니다. 이 기능이 되돌릴 수 없는 이유는 두 가지입니다. 연장이 적용된 후에는 되돌릴 방법이 없으며, 가족 구성원의 구독은 자동으로 연장되지만 가족 구성원 구독에 대한 직접 요청은 지원되지 않습니다. 또한 연장 기간은 Apple에서 수수료율을 산정할 때 기준이 되는 1년 유료 서비스 기간에 포함되지 않습니다.
9단계 — 의존하기 전에 파이프라인이 작동하는지 검증하세요
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.
10단계 — 파이프라인을 올바르게 유지하는 운영 규칙
- 무엇이든 작성하기 전에
환경을 읽으세요. 샌드박스 트래픽은 샌드박스 URL에 도달합니다. 공유 핸들러가 샌드박스 이벤트로 프로덕션 권한을 부여하면 테스트가 데이터 사고로 이어집니다. notificationUUID를 기준으로 중복을 제거하세요. 재시도와 자체 재처리로 같은 이벤트가 여러 번 발생합니다. 식별자를 저장하고 중복은 버리세요.- 알림을 영수증으로 취급해서는 안 됩니다.
SUBSCRIBED와DID_RENEW만 수신하고REFUND,REVOKE,REFUND_REVERSED를 무시하는 빌드는 유료 접근 권한을 영구적으로 누출시킵니다. 전체 생명주기를 처리하거나 검증을 Apple의 라이브러리에 맡기고 Server API에 질의하세요. - 자체 이벤트 로그를 보관하세요. 고객이 접근 권한에 이의를 제기할 때, 알림 기록과 자체 로그가 결정을 재구성할 수 있게 해줍니다.
- 엔드포인트가 프로덕션의 일부가 된다는 점을 염두에 두세요. 모니터링, 연결 예산보다 훨씬 짧은 요청 타임아웃, 그리고 큐가 필요합니다. 결제 시스템으로 이어지는 동기 호출 체인은 안 됩니다.
출처
- Apple 개발자 — App Store 서버 알림: developer.apple.com/documentation/appstoreservernotifications
- Apple 개발자 — App Store 서버 알림 V2: app-store-server-notifications-v2
- Apple 개발자 — App Store 서버 알림 활성화: enabling-app-store-server-notifications
- Apple 개발자 — notificationType 및 subtype 열거형: notificationtype / subtype
- Apple 개발자 — responseBodyV2DecodedPayload: responsebodyv2decodedpayload
- Apple 개발자 — App Store 서버 API: developer.apple.com/documentation/appstoreserverapi
- Apple — App Store 서버 라이브러리(Python): github.com/apple/app-store-server-library-python
- Apple — 인증 기관: www.apple.com/certificateauthority
개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.
메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.
← 수정으로 돌아가기