Descripción general

Los webhooks son notificaciones sobre eventos que se producen en el sistema. Cuando ocurre un evento específico, Xsolla envía una solicitud HTTP, en la cual se transmiten los datos del evento, a su aplicación. Generalmente, se trata de una solicitud POST en formato JSON.

Ejemplos de eventos:

• interacción del usuario con un catálogo de artículos
• pago o cancelación de un pedido

Cuando se produce un evento definido, Xsolla lo notifica a su sistema mediante un webhook. En consecuencia, puede realizar acciones como:

• reponer el saldo del usuario
• efectuar una devolución de pago
• abonar o cargar nuevos artículos en la cuenta de usuario
• empezar a proveer una suscripción
• bloquear a un usuario si hay una sospecha de fraude

Ejemplo de un flujo de trabajo de webhook de procesamiento de pagos:

Videoguía para la integración de webhooks con Xsolla:

Configuración de Webhooks para trabajar con productos y soluciones de Xsolla:

Lista de webhooks requeridos

Si utiliza productos y soluciones que requieren trabajar con webhooks, active y pruebe los webhooks en su Cuenta del editor y establezca su procesamiento. Cuando se producen eventos específicos, los webhooks se envían secuencialmente. Por lo tanto, si no procesa uno de los webhooks, no se enviarán los posteriores. La lista de webhooks requeridos se muestra a continuación.

In-Game Store y Payments

Se han configurado 2 opciones de envío de webhook por parte de Xsolla al comprar y devolver artículos en el sitio: la información con los datos de pago y transacción, y la información sobre los artículos comprados pueden enviarse por separado o pueden combinarse en un solo webhook.

Recibir información en webhooks combinados:

Si se registró en Cuenta del editor después del 22 de enero de 2025, recibirá toda la información en los webhooks Successful payment for order (order_paid) y Order cancellation (order_canceled). En este caso, no es necesario procesar los webhooks Payment (payment) y Refund (refund).

Recibir información en webhooks separados:

Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, recibirá los siguientes webhooks:

• Pago (payment) y Reembolso (refund) con información sobre los datos de pago y los detalles de la transacción.
• Successful payment for order (order_paid) y Order cancellation (order_canceled) con información sobre los artículos comprados.

Debe procesar todos los webhooks entrantes. Para cambiar a la nueva opción con la recepción de webhooks combinados, contacte con sus gestores de éxito del cliente o escriba a csm@xsolla.com.

Para el funcionamiento completo de la tienda del juego y la gestión de pagos, es necesario implementar el procesamiento de los principales webhooks.

Si recibe webhooks combinados:

Si recibe webhooks por separado:

Si la personalización del catálogo de artículos se implementa en el lado de su aplicación, establezca el procesamiento del webhook Personalización del catálogo en el lado del socio.

Suscripciones

Para gestionar automáticamente los planes de suscripción, es necesario implementar el procesamiento de los principales webhooks:

• Validación del usuario (user_validation): se envía en diferentes etapas del proceso de pago para garantizar que el usuario esté registrado en el juego.
• Pago (payment): se envía cuando se paga un pedido y contiene los datos del pago y los detalles de la transacción.
• Suscripción creada (create_subscription): se envía cuando se ha procesado correctamente un webhook de Pago o el usuario ha adquirido una suscripción con un periodo de prueba. Contiene los detalles de la suscripción adquirida y los datos del usuario. Use los datos del webhook para agregar una suscripción al usuario.
• Suscripción actualizada (update_subscription): se envía cuando se renueva o modifica una suscripción, cuando se ha procesado correctamente un webhook de Pago. Contiene los detalles de la suscripción adquirida y los datos del usuario. Use los datos del webhook para ampliar la suscripción del usuario o cambiar los parámetros de la suscripción.
• Reembolso (refund): se envía cuando se cancela un pedido y contiene los datos del pago cancelado y los detalles de la transacción.
• Suscripción cancelada (cancel_subscription): se envía cuando se ha procesado correctamente un webhook de Reembolso o se ha cancelado la suscripción por otro motivo. Contiene información sobre la suscripción y los datos del usuario. Use los datos del webhook para sustraer al usuario las suscripciones adquiridas.

Establecer webhooks en Cuenta del editor

Configuración general

Para habilitar la recepción de webhooks:

1. En el proyecto en la Cuenta del editor vaya a Project Settings > Webhooks.
2. En el campo Webhook server, especifique la URL de su servidor en el que desea recibir webhooks en el formato https://example.com. También puede especificar la URL que encuentre en una herramienta para probar webhooks.

3. Por defecto, se genera una clave secreta para firmar los webhooks del proyecto. Si desea generar una nueva clave secreta, haga clic en el icono de actualización.
4. Haga clic en Enable webhooks.

Para deshabilitar la recepción de webhooks:

1. En el proyecto en la Cuenta del editor vaya a Project Settings > Webhooks.
2. Haga clic en Disable webhooks.

Configuración avanzada

Para los webhooks de la sección Payments and Store, hay opciones de configuración avanzada disponibles. Aparecerán automáticamente en el bloque General settings después de hacer clic en el botón Get webhooks.

En esta sección puede configurar la recepción de información adicional en webhooks. Para ello, active la opción. La línea de cada permiso indica los webhooks que se verán afectados al cambiar la configuración.

Probar webhooks en Cuenta del editor

Probar los webhooks ayuda a asegurar la correcta configuración del proyecto tanto en su lado como en el lado de Xsolla.

Si los webhooks están establecidos correctamente, aparecerá una sección de prueba de webhooks bajo la sección de configuración de webhooks.

La sección de pruebas de la Cuenta del editor varía en función de la opción de recepción del webhook.

Si recibe webhooks combinados:

Si recibe webhooks por separado:

A continuación se describe el proceso de pruebas para el escenario con webhooks combinados.

Payments and Store

En la pestaña Payments and Store, puede probar los siguientes webhooks:

• Validación del usuario (user_validation)
• Successful payment for order (order_paid)
• Cancelación del pedido (order_canceled)

Para realizar la prueba:

1. En la sección de pruebas de webhooks, vaya a la pestaña Payments and Store.

2. En el menú desplegable, seleccione el tipo de artículo. Si el artículo del tipo seleccionado no está establecido en Cuenta del editor, haga clic en:

   • Connect: si el módulo con artículos de este tipo no está conectado.
   • Configure: si conectó el módulo anteriormente, pero no ha finalizado la configuración
     Cuando haga clic en el botón, se le redirigirá a la sección de Cuenta del editor correspondiente al tipo de artículo seleccionado. Cuando haya creado el artículo, vuelva a la sección de pruebas de webhooks y proceda al siguiente paso.

3. Rellene los campos necesarios:

   1. Seleccione el SKU de los artículos en la lista desplegable e indique la cantidad. Puede elegir varios artículos del mismo tipo haciendo clic en + y añadiéndolos en una nueva línea.
   2. User ID: al realizar la prueba, puede utilizar cualquier combinación de letras y dígitos.
   3. Public user ID: ID conocido por un usuario, por ejemplo, un correo electrónico o un apodo. Este campo se muestra si el ID de usuario público está habilitado en su proyecto en Pay Station > Settings.
   4. Introduzca cualquier valor en el campo Xsolla Order ID.
   5. Xsolla Invoice ID: ID de transacción en el lado de Xsolla. Al realizar la prueba, puede usar cualquier valor numérico.
   6. Invoice ID: ID de transacción del lado de su juego. Al realizar la prueba, puede utilizar cualquier combinación de letras y dígitos. No es un parámetro requerido para pagar correctamente, pero puede transmitirlo para enlazar el ID de transacción de su lado con el ID de transacción del lado de Xsolla.
   7. Amount: cantidad del pago. Al realizar la prueba, puede utilizar cualquier valor numérico.

4. Currency: seleccione una moneda de la lista desplegable.

5. Haga clic en Test webhooks.

Los webhooks User validation, Successful payment for order y Order cancellation con los datos especificados se envían a la URL facilitada. Los resultados de la prueba de cada tipo de webhook se muestran debajo del botón Test webhooks.

Si el ID de usuario público está activado en su proyecto, también verá los resultados de una comprobación de búsqueda de usuarios.

Para cada webhook, tiene que establecer el procesamiento de ambos escenarios: uno, satisfactorio, y el otro, fallido.

Suscripciones

En la pestaña Subscriptions puede probar los siguientes webhooks:

• Validación del usuario (user_validation)
• Pago (payment)

Para realizar pruebas:

1. En la sección de pruebas, vaya a la pestaña Subscriptions.
2. Rellene los campos necesarios:
   1. User ID: al realizar la prueba, puede usar cualquier combinación de letras y dígitos.
   2. Xsolla Invoice ID: ID de transacción en el lado de Xsolla. Cuando realice pruebas, puede usar cualquier valor numérico.
   3. Public user ID: ID conocido por un usuario, p. ej., un correo electrónico o un alias. Este campo se muestra si el ID público de usuario está habilitado en su proyecto en la sección Pay Station > Settings > Additional settings.
   4. Currency: seleccione una moneda de la lista desplegable.
   5. Plan ID: un plan de suscripción. Elija un plan de la lista desplegable.
   6. Subscription product: elija un producto de la lista desplegable (opcional).
   7. Amount: importe del pago. Al realizar pruebas, puede usar cualquier valor numérico.
   8. Invoice ID: ID de transacción en el lado del juego. Cuando realice pruebas, puede usar cualquier combinación de letras y dígitos. No es un parámetro obligatorio para que el pago sea aceptado, pero puede transmitirlo para vincular el ID de transacción de su lado con el ID de transacción del lado de Xsolla.
   9. Periodo de prueba. Para probar la comp ra de una suscripción sin periodo de prueba o para probar la renovación de una suscripción, especifique el valor 0.
3. Haga clic en Test webhooks.

En la URL especificada, recibirá webhooks con datos rellenados. Los resultados de las pruebas de cada webhook, tanto para un escenario con satisfactorio como para un escenario fallido, se muestran bajo el botón Test webhooks.

Agente de escucha de webhooks

El agente de escucha es un código de programa que permite recibir webhooks entrantes en una dirección URL especificada, generar una firma y enviar una respuesta al servidor de webhooks de Xsolla.

En el lado de su aplicación, implemente la recepción de webhooks desde las siguientes direcciones IP:

• 185.30.20.0/24
• 185.30.21.0/24
• 185.30.22.0/24
• 185.30.23.0/24
• 34.102.38.178
• 34.94.43.207
• 35.236.73.234
• 34.94.69.44
• 34.102.22.197

Si ha integrado el producto Login, añada webhooks de procesamiento desde las siguientes direcciones IP:

• 34.94.0.85
• 34.94.14.95
• 34.94.25.33
• 34.94.115.185
• 34.94.154.26
• 34.94.173.132
• 34.102.48.30
• 35.235.99.248
• 35.236.32.131
• 35.236.35.100
• 35.236.117.164

Limitaciones:

• En la base de datos de su aplicación no debería haber varias transacciones aceptadas con el mismo ID.
• Si el agente de escucha de webhooks recibió un webhook con un ID que ya existe en la base de datos, deberá devolver el resultado del procesamiento anterior de esta transacción. No se recomienda acreditar al usuario una compra duplicada ni crear registros duplicados en la base de datos.

Generación de firma

Para garantizar una transmisión de datos segura, debe comprobar que el webhook se ha enviado desde el servidor de Xsolla y que no ha sido manipulado durante el tránsito. Para ello, genere su propia firma basada en la carga útil del cuerpo de la solicitud y compárela con la firma proporcionada en el encabezado authorization de la solicitud entrante. Si las firmas coinciden, significa que el webhook es auténtico y seguro de procesar.

Pasos de verificación:

1. Obtenga la firma del encabezado authorization de la solicitud de webhook entrante. El formato del encabezado es Signature <signature_value>.

2. Obtenga el cuerpo de la solicitud del webhook en formato JSON.

   Atención

   Utilice la carga JSON tal y como la recibió. No analice ni recodifique la carga útil, ya que modificaría el formato y provocaría un error en la verificación de la firma.

3. Genere su propia firma para comparar:

   1. Concatene la carga JSON con la clave secreta de su proyecto al añadir la clave al final de la cadena.
   2. Aplique la función hash criptográfica SHA-1 a la cadena obtenida. El resultado será una cadena hexadecimal en minúsculas.

4. Compare su firma generada con la del encabezado authorization. Si coinciden, significa que el webhook es auténtico.

A continuación encontrará ejemplos de implementación de generación de firmas para los siguientes lenguajes: C#, C++, Go, PHP y Node.js.

Ejemplo de webhook (HTTP):

Ejemplo de webhook (curl):

Ejemplo C# de implementación de generación de firmas (muestra general):

Ejemplo C# de implementación de generación de firmas (.NET 5.0 y posteriores):

Ejemplo C# de implementación de generación de firmas (.NET 7.0 y posteriores):

Ejemplo C++ de implementación de generación de firmas:

Ejemplo Go de implementación de generación de firmas:

Ejemplo PHP de implementación de generación de firmas:

Ejemplo Node.js de implementación de generación de firmas:

Enviar respuestas al webhook

Para confirmar la recepción del webhook, su servidor debe devolver:

• Código HTTP "200", "201" o "204" en el caso de una respuesta satisfactoria.
• Código HTTP "400" con la descripción del problema si no se encontró el usuario especificado o se transmitió una firma no válida. Su gestor de webhooks también puede devolver un código HTTP "5xx" si hay problemas temporales en su servidor.

Si el servidor de Xsolla no ha recibido respuesta a los webhooks Successful payment for order y Order cancellation o ha recibido una respuesta con un código 5xx, los webhooks se reenvían de la siguiente manera:

• 2 intentos con un intervalo de 5 minutos
• 7 intentos con un intervalo de 15 minutos
• 10 intentos con un intervalo de 60 minutos

Se realiza un máximo de 20 intentos de envío de webhooks en un plazo de 12 horas desde el primer intento.

La lógica de reintento para los webhooks de pago y reembolso se describe en la página del webhook correspondiente.

Si el servidor de Xsolla no ha recibido respuesta al webhook User validation o ha recibido una respuesta con un código 400 o 5xx, el webhook User validation no se reenvía. En este caso, el usuario ve un error y los webhooks Payment y Successful payment for order no se envían.

Errores

Códigos de error para el código HTTP 400:

Lista de webhooks