La integración de webhook de Adapty consta de los siguientes pasos:

1. Configuras tu endpoint:
   1. Asegúrate de que tu servidor pueda procesar las solicitudes de Adapty con el encabezado Content-Type configurado como application/json.
   2. Configura tu servidor para recibir la solicitud de verificación de Adapty y responder con cualquier estado 2xx y un cuerpo JSON.
   3. Gestiona los eventos de suscripción una vez verificada la conexión.
2. Configuras y activas la integración del webhook en el Adapty Dashboard. También puedes mapear los eventos de Adapty a nombres de eventos personalizados. Te recomendamos probar en el entorno Sandbox antes de pasar a producción.
3. Adapty envía una solicitud de verificación a tu servidor.
4. Tu servidor responde con un estado 2XX y un cuerpo JSON.
5. Una vez que Adapty recibe una respuesta válida, comienza a enviar eventos de suscripción.

Configura tu servidor para procesar las solicitudes de Adapty

Adapty enviará a tu endpoint de webhook 2 tipos de solicitudes:

1. Solicitud de verificación: la solicitud inicial para verificar que la conexión está configurada correctamente. Esta solicitud no contendrá ningún evento y se enviará en el momento en que hagas clic en el botón Save en la integración de Webhook del Adapty Dashboard. Para confirmar que tu endpoint recibió correctamente la solicitud de verificación, tu endpoint debe responder con la respuesta de verificación.
2. Evento de suscripción: una solicitud estándar que el servidor de Adapty envía cada vez que se crea un evento en él. Tu servidor no necesita responder con ninguna respuesta específica. Lo único que necesita el servidor de Adapty es recibir una respuesta HTTP estándar con código 200 si recibe el mensaje correctamente.

Solicitud de verificación

Después de habilitar la integración de webhook en el Adapty Dashboard, Adapty enviará una solicitud POST de verificación que contiene un objeto JSON vacío {} como cuerpo.

Configura tu endpoint para que tenga el encabezado Content-Type como application/json, es decir, el endpoint de tu servidor debe esperar que la solicitud webhook entrante tenga su payload en formato JSON.

Tu servidor debe responder con un código de estado 2xx y enviar cualquier respuesta JSON válida, por ejemplo:

{}

Una vez que Adapty recibe la respuesta de verificación en el formato correcto y con un código de estado 2xx, tu integración de webhook con Adapty está completamente configurada.

Eventos de suscripción

Los eventos de suscripción se envían con la cabecera Content-Type establecida en application/json y contienen datos del evento en formato JSON. Para conocer los posibles tipos de eventos y las estructuras de solicitud, consulta Tipos de eventos y campos del webhook.

Configurar la integración de webhook en el Adapty Dashboard

Dentro de Adapty, puedes configurar flujos separados para los eventos de producción y los eventos de prueba recibidos desde el entorno sandbox de Apple o Stripe, o desde la cuenta de prueba de Google.

Para los eventos de producción, usa el campo Production endpoint URL para especificar la URL a la que se enviarán los callbacks. Además, configura el campo Authorization header value for production endpoint — la cabecera que usará tu servidor para autenticar los eventos de Adapty. Ten en cuenta que el valor especificado en el campo Authorization header value for production endpoint se usará como cabecera Authorization exactamente tal como se proporciona, sin ningún cambio ni añadido.

Para los eventos de prueba, utiliza los campos Sandbox endpoint URL y Authorization header value for sandbox endpoint según corresponda. Para configurar la integración con webhook:

1. Abre Integrations -> Webhook en tu Adapty Dashboard.

2. Activa el interruptor para iniciar la integración.
3. Rellena los campos de la integración:

   Campo	Descripción
   Production endpoint URL	La URL que usa Adapty para enviar solicitudes HTTP POST de eventos en producción.
   Authorization header value for production endpoint	El encabezado que tu servidor usará para autenticar las solicitudes de Adapty en producción. Ten en cuenta que utilizaremos el valor especificado en este campo como encabezado Authorization exactamente como se proporcione, sin ningún cambio ni adición. Aunque no es obligatorio, se recomienda encarecidamente para mayor seguridad.

Además, para tus necesidades de pruebas en el entorno sandbox, hay otros dos campos disponibles:

Campo de prueba	Descripción
Sandbox endpoint URL	La URL que usa Adapty para enviar solicitudes HTTP POST de eventos en el entorno sandbox.
Authorization header value for sandbox endpoint	El encabezado que usará tu servidor para autenticar las solicitudes de Adapty durante las pruebas en el entorno sandbox. Ten en cuenta que usaremos el valor especificado en este campo como encabezado Authorization exactamente como se proporcionó, sin ningún cambio ni adición. Aunque no es obligatorio, se recomienda encarecidamente para mayor seguridad.

4. (opcional) Elige los eventos que quieres recibir y asigna sus nombres. Consulta nuestros Flujos de eventos para ver qué eventos se disparan en cada situación.

   Si los IDs de tus eventos son distintos a los que usa Adapty, mantenlos tal como están en tu sistema y sustituye los IDs de eventos predeterminados de Adapty por los tuyos en la sección Events names de la página Integrations -> Webhooks. El ID de evento puede ser cualquier cadena; simplemente asegúrate de que el ID de evento en tu servidor de procesamiento de webhooks coincida con el que introdujiste en el Adapty Dashboard. No puedes dejar el ID de evento vacío para los eventos habilitados.

5. Los campos y opciones adicionales no son obligatorios; úsalos según necesites:

   Ajuste	Descripción
   Send Trial Price	Cuando está activado, Adapty incluirá el precio de la suscripción en los campos price_local y price_usd para el evento Trial Started.
   Exclude Historical Events	Permite excluir eventos ocurridos antes de que el usuario instalara la app con el SDK de Adapty. Esto evita la duplicación de eventos y garantiza informes precisos. Por ejemplo, si un usuario activó una suscripción mensual el 10 de enero y actualizó la app con el SDK de Adapty el 6 de marzo, Adapty omitirá los eventos anteriores al 6 de marzo y conservará los posteriores.
   Send user attributes	Activa esta opción para enviar atributos específicos del usuario, como preferencias de idioma. Estos atributos aparecerán en el campo user_attributes. Consulta Campos del evento para más información.
   Send attribution	Activa esta opción para incluir información de atribución (p. ej., datos de AppsFlyer) en el campo attributions. Consulta la sección Datos de atribución para más detalles.
   Send Play Store purchase token	Activa esta opción para recibir el token de Play Store necesario para la revalidación de compras, si fuera necesario. Al activarla, se añadirá el parámetro play_store_purchase_token al evento. Para más detalles sobre su contenido, consulta la sección Token de compra de Play Store.

6. Recuerda hacer clic en el botón Save para confirmar los cambios.

En el momento en que hagas clic en el botón Save, Adapty enviará una solicitud de verificación y esperará la respuesta de verificación de tu servidor.

Elige los eventos a enviar y mapea los nombres de eventos

Elige los eventos que quieres recibir en tu servidor activando el interruptor correspondiente. Si los nombres de tus eventos son distintos a los que usa Adapty y necesitas mantener los tuyos, puedes configurar el mapeo reemplazando los nombres de eventos predeterminados de Adapty por los tuyos en la sección Events names de la página Integrations -> Webhooks.

El nombre del evento puede ser cualquier cadena de texto. No puedes dejar los campos vacíos para los eventos habilitados. Si borraste accidentalmente el nombre de un evento de Adapty, siempre puedes copiarlo desde el artículo Eventos para enviar a integraciones de terceros.

Manejar eventos de webhook

Los webhooks generalmente se entregan entre 5 y 60 segundos después de que ocurre el evento. Sin embargo, los eventos de cancelación pueden tardar hasta 2 horas en entregarse tras la cancelación de una suscripción por parte del usuario.

Si el código de estado de respuesta de tu servidor está fuera del rango 200-404, Adapty reintenta la entrega con retroceso exponencial. El primer reintento ocurre aproximadamente 1 minuto después del fallo inicial, duplicándose en cada intento sucesivo — hasta 9 reintentos distribuidos a lo largo de 24 horas. Te recomendamos que configures tu webhook para realizar solo una validación básica del cuerpo del evento de Adapty antes de responder. Si tu servidor no puede procesar el evento y no quieres que Adapty reintente, usa un código de estado dentro del rango 200-404. Además, gestiona cualquier tarea que consuma tiempo de forma asíncrona y responde a Adapty con rapidez. Si Adapty no recibe respuesta en 10 segundos, considerará el intento como fallido y lo reintentará.