8 min de lectura

App Store Server Notifications V2: guía para configurarlas

Guía ES-CO para recibir en tu backend las renovaciones, cobros fallidos y reembolsos de iOS: configura la URL V2 en App Store Connect, responde bien a Apple, valida el signedPayload, entiende los tipos de notificación y pruébalo en sandbox.

Portada: Avisos en tiempo real, Notificaciones del servidor de App Store, con tarjeta Notificación V2: URL de producción y eventos renovación, cobro fallido y reembolso con 200 OK

Si vendes suscripciones o compras integradas en iOS, tu servidor necesita enterarse de lo que pasa fuera de la app: renovaciones, cancelaciones, cobros fallidos y reembolsos. Para eso existen las App Store Server Notifications, avisos que Apple envía directamente a tu backend en tiempo real. En esta guía en español configuras la versión 2 (V2) paso a paso: la URL en App Store Connect, la respuesta de tu servidor, los tipos de notificación que más importan y cómo probar todo antes de salir a producción.

Qué son las App Store Server Notifications

Son un servicio server-to-server: cada vez que ocurre un evento de compra integrada, el App Store hace un POST a una URL HTTPS de tu servidor. Con esa información actualizas la base de datos de usuarios, das o quitas acceso y reaccionas a reembolsos sin depender de que el usuario abra la app.

Hay dos versiones. La versión 1 está obsoleta (deprecated); Apple pide implementar la versión 2 en cualquier integración nueva. Si todavía usas V1, la recomendación oficial es probar V2 en sandbox antes de cambiar producción.

Requisitos de tu servidor antes de configurar

Antes de tocar App Store Connect, deja listo el endpoint:

  • HTTPS con TLS 1.2 o superior. Apple no envía a URLs sin cifrado.
  • Puerto 443 o uno igual o mayor a 1024. Por ejemplo, https://api.tuapp.com:1234/asn es válido.
  • Lista de IP permitidas. Si tu firewall filtra por IP, agrega la subred 17.0.0.0/8, que aplica a sandbox y producción.
  • Una URL para producción y, opcionalmente, otra para sandbox. Puedes usar la misma para ambas.

Cómo configurar App Store Server Notifications V2 en App Store Connect

Necesitas el rol Account Holder, Admin, App Manager o Marketing.

  1. En Apps, abre tu app.
  2. En la barra lateral, en General, entra a App Information (Información de la app).
  3. Baja hasta General Information y busca la sección App Store Server Notifications.
  4. En Production Server URL, haz clic en Set Up URL.
  5. Escribe la URL de tu endpoint.
  6. Elige Version 2 (la versión 1 aparece marcada como obsoleta).
  7. Haz clic en Save.
  8. Repite los pasos en Sandbox Server URL para tus pruebas.

Dos detalles que causan confusión:

  • Si no configuras una URL de sandbox, Apple envía las notificaciones de ambos entornos a la URL de producción.
  • Si solo configuras sandbox, no recibirás nada en producción.

No hace falta publicar una nueva versión de la app para activar o cambiar estas URLs. Si todavía no tienes tus productos creados, primero sigue la guía de suscripciones en App Store Connect.

Cómo debe responder tu servidor

Apple solo mira el código HTTP de tu respuesta; no necesitas devolver datos.

Respuesta de tu servidorQué entiende Apple
200 a 206Notificación recibida
40x o 50xFalló: la reintentará
Cualquier otro códigoEnvío no exitoso

En producción, si no recibe un código de éxito, Apple reintenta la notificación V2 cinco veces: a la 1, 12, 24, 48 y 72 horas después del intento anterior. En sandbox solo hay un intento, sin reintentos, así que una caída durante las pruebas se traduce en una notificación perdida.

Un patrón práctico: guarda la notificación en bruto, responde 200 de inmediato y procésala después en una cola.

Qué trae una notificación V2: signedPayload

El cuerpo del POST es un JSON con un único campo, signedPayload. Es un JWS (JSON Web Signature) firmado por Apple. Para leerlo:

  1. Separa el encabezado, el payload y la firma del JWS.
  2. Valida la firma con el algoritmo indicado en el campo alg del encabezado. No confíes en el contenido sin verificarlo.
  3. Decodifica el payload (Base64URL). Ahí encuentras notificationType, subtype, notificationUUID y el objeto data.
  4. Dentro de data, decodifica también signedTransactionInfo (la transacción) y, según el tipo, signedRenewalInfo (la información de renovación). Ambos vienen firmados.

Para no escribir esta validación desde cero, Apple publica la App Store Server Library para Swift, Java, Python y Node.js, con utilidades para verificar y decodificar notificaciones y transacciones firmadas.

Evita procesar duplicados

Cada notificación trae un notificationUUID único. Guárdalo con una restricción de unicidad en tu base de datos e ignora los repetidos: con los reintentos es normal recibir la misma notificación más de una vez.

Tipos de notificación que más vas a usar

Los eventos más comunes de una app con suscripciones, según la documentación de Apple:

EventonotificationTypesubtype
Primera suscripción en el grupoSUBSCRIBEDINITIAL_BUY
Vuelve a suscribirse tras vencerSUBSCRIBEDRESUBSCRIBE
Renovación automática exitosaDID_RENEW—
Desactiva la renovación automáticaDID_CHANGE_RENEWAL_STATUSAUTO_RENEW_DISABLED
Mejora de plan en el mismo grupoDID_CHANGE_RENEWAL_PREFUPGRADE
Baja de plan en el mismo grupoDID_CHANGE_RENEWAL_PREFDOWNGRADE
Falla el cobro y entra en reintentoDID_FAIL_TO_RENEW— o GRACE_PERIOD
Se recupera el cobroDID_RENEWBILLING_RECOVERY
Vence por cancelaciónEXPIREDVOLUNTARY
Vence tras agotar el reintento de cobroEXPIREDBILLING_RETRY
Canjea una oferta con suscripción activaOFFER_REDEEMED—
Apple reembolsa la compraREFUND—
Pierde acceso por En FamiliaREVOKE—

Cómo traducirlo a lógica de negocio:

  • DID_FAIL_TO_RENEW con GRACE_PERIOD: mantén el acceso mientras dure el periodo de gracia y muestra un aviso para actualizar el método de pago.
  • AUTO_RENEW_DISABLED: el usuario sigue con acceso hasta el final del periodo pagado; es un buen momento para una oferta de retención, no para cortar el servicio.
  • REFUND y REVOKE: retira el acceso al contenido asociado a esa transacción.

Apple sigue agregando valores al registro de cambios (por ejemplo, para compras de varios puestos en 2026), así que procesa los tipos que conoces y registra los desconocidos en lugar de fallar.

Cómo probar las notificaciones antes de publicar

  1. Configura la URL de sandbox en App Store Connect.
  2. Pide una notificación de prueba con el endpoint Request a Test Notification de la App Store Server API. Apple envía una notificación de tipo TEST a tu URL (formato V2 aunque tengas V1 configurada) y te devuelve un testNotificationToken.
  3. Consulta el resultado con Get Test Notification Status usando ese token. Te dice cómo respondió tu servidor.
  4. Haz compras reales de prueba con una cuenta de sandbox: sigue la guía de sandbox tester en App Store Connect para crearla y verás llegar SUBSCRIBED, DID_RENEW y los demás tipos con renovaciones aceleradas.

Para llamar a la App Store Server API necesitas una clave de compras integradas (In-App Purchase key) generada en App Store Connect. No es la misma clave de la API de App Store Connect, aunque ambas se crean en Users and Access > Integrations.

Si tu servidor se cae: recupera lo perdido

  • Get Notification History devuelve las notificaciones V2 que Apple intentó enviarte: hasta 180 días en producción y 30 días en sandbox, en páginas de 20 registros. Puedes filtrar por tipo, subtipo o por transactionId.
  • Esos registros reflejan el estado en el momento del envío. Para el estado actual de una suscripción, usa Get All Subscription Statuses; para otros tipos de compra, Get Transaction History.

¿Usas RevenueCat? Apple permite una sola URL de producción por app, así que la URL debe ser la que te da RevenueCat y, si quieres los eventos en tu backend, reenviarlos desde allí. En la guía de RevenueCat con Flutter ves cómo encaja en el flujo de compras.

Preguntas frecuentes

¿Cuál es la diferencia entre App Store Server Notifications V1 y V2?

La V1 está obsoleta. La V2 envía un signedPayload firmado en formato JWS, se reintenta cinco veces en producción (la V1, tres) y permite recuperar el historial con Get Notification History.

¿Dónde pongo la URL de App Store Server Notifications?

En App Store Connect > tu app > App Information > App Store Server Notifications, en los campos Production Server URL y Sandbox Server URL.

¿Cómo hago un test de App Store Server Notifications?

Llama al endpoint Request a Test Notification de la App Store Server API y revisa el resultado con Get Test Notification Status.

¿Llegan reintentos en sandbox?

No. En sandbox Apple intenta enviar cada notificación una sola vez; los reintentos solo existen en producción.

Deja lista tu ficha mientras programas el backend

En AppConsol generas gratis las capturas de pantalla, los íconos y la política de privacidad que te piden App Store y Google Play. Pruébalo hoy y ten tu ficha lista para cuando tus suscripciones salgan a producción.

Sigue aprendiendo