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:

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:

Producto/Solución	Obligatorio/Opcional	¿Para qué se utilizan los webhooks?
Payments	Obligatorio	Validación del usuario. Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago. Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.
In-Game Store	Obligatorio	Validación del usuario. Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago. Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.
Game Sales	Opcional	Para vender claves del juego, la validación del usuario y el abono de los artículos no son necesarios. Puede conectar los webhooks si desea recibir información sobre eventos, como el pago o la cancelación de pedidos. Si conecta webhooks, es esencial procesar todos los webhooks requeridos entrantes.
Suscripciones	Opcional	Recibir información sobre la creación, actualización o cancelación de una suscripción. También puede solicitar información mediante la API.
Web Shop	Obligatorio	Validación del usuario. Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago. Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido. Autenticación de usuario, si usa la autenticación mediante ID de usuario. Como alternativa, puede utilizar autenticación de usuario mediante Xsolla Login.
Digital Distribution Hub	Obligatorio	Validación del usuario. Vincular el ID de transacción en el lado de Xsolla con el ID de transacción en su sistema. Transferir parámetros de transacción adicionales en el pedido. Abonar al usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido. Consulte la documentación para obtener información detallada sobre la configuración de webhooks para el Digital Distribution Hub.

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.

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 Pago del pedido realizado correctamente (order_paid) y Cancelación del pedido (order_canceled). En este caso, no es necesario procesar los webhooks Pago (payment) y Reembolso (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.
• Pago del pedido realizado correctamente (order_paid) y Cancelación del pedido (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:

Nombre y tipo de webhook	Descripción
Validación del usuario > 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.
Servicios de juego > Webhooks combinados > Pago del pedido realizado correctamente (order_paid)	Contiene datos de pago, detalles de la transacción e información sobre los artículos comprados. Utilice los datos del webhook para añadir artículos al usuario.
Servicios de juego > Webhooks combinados > Cancelación del pedido (order_canceled)	Contiene datos del pago cancelado, detalles de la transacción e información sobre los artículos comprados. Utilice los datos del webhook para eliminar los artículos comprados.

Si recibe webhooks por separado:

Nombre y tipo de webhook	Descripción
Validación del usuario > 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.
Pagos > Pago (payment)	Contiene los datos del pago y los detalles de la transacción.
Servicios de juego > Webhooks separados > Pago del pedido realizado correctamente (order_paid)	Contiene información sobre los artículos comprados. Utilice los datos del webhook para añadir artículos al usuario.
Pagos > Reembolso (refund)	Contiene los datos del pago y los detalles de la transacción.
Servicios de juego > Webhooks separados > Cancelación del pedido (order_canceled)	Contiene información sobre los artículos comprados y el ID de la transacción cancelada. Utilice los datos del webhook para eliminar los artículos comprados.

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.

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.

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.

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.

Selector	Descripción
Mostrar información sobre la cuenta de pago guardada	La información sobre el método de pago guardado se transmite en el objeto personalizado payment_account.
Mostrar información sobre las transacciones mediante los métodos de pago guardados	La información se transmite en los siguientes parámetros personalizados del webhook: saved_payment_method: 0: no se utilizó el método de pago guardado 1: el método de pago se guardó al realizar el pago actual 2: se utiliza el método de pago guardado previamente payment_type: 1: pago único 2: pago periódico
Añadir objeto del pedido al webhook	La información sobre el pedido se transmite en el objeto order del webhook Pago.
Enviar solamente los parámetros de usuario necesarios sin datos confidenciales	Solamente la siguiente información sobre el usuario se transmite en el webhook: ID país
Enviar parámetros personalizados	La información sobre los parámetros de token personalizados se transmite en el webhook.
Mostrar número de BIC y sufijo de la tarjeta	La siguiente información sobre el número de tarjeta bancaria se transmite en el webhook: los 6 primeros dígitos del parámetro card_bin los 4 últimos dígitos del card_suffix
Mostrar marca de tarjeta	La marca de la tarjeta empleada para realizar el pago. Por ejemplo, Mastercard o Visa.

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.

Sección de pruebas 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:

Nombre de la pestaña para pruebas de webhook	Nombre y tipo de webhook
Payments and store	Validación del usuario > Validación del usuario (user_validation)
	Servicios de juego > Webhooks combinados > Pago del pedido realizado correctamente (order_paid)
	Servicios de juego > Webhooks combinados > Cancelación del pedido (order_canceled)
Subscriptions	Validación del usuario > Validación del usuario (user_validation)
	Pagos > Pago (payment)

Si recibe webhooks por separado:

Nombre de la pestaña para pruebas de webhook	Nombre y tipo de webhook
Store	Servicios de juego > Webhooks separados > Pago del pedido realizado correctamente (order_paid)
	Servicios de juego > Webhooks separados > Cancelación del pedido (order_canceled)
Payments	Validación del usuario > Validación del usuario (user_validation)
	Pagos > Pago (payment)
Subscriptions	Validación del usuario > Validación del usuario (user_validation)
	Pagos > Pago (payment)

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

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

• Validación del usuario (user_validation)
• Pago del pedido realizado correctamente (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.
   8. Currency: seleccione una moneda de la lista desplegable.

4. Haga clic en Test webhooks.

Los webhooks Validación del usuario, Pago del pedido realizado correctamente y Cancelación del pedido con los datos especificados se envían a la URL proporcionada. 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.

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 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.

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.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197.

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.

Cuando reciba un webhook, debe garantizar la seguridad de la transmisión de los datos. Para ello, se debe generar una firma a partir de los datos del webhook y verificar que coincide con la firma enviada en el encabezado de la solicitud HTTP. Para generar una firma:

1. Concatene el JSON del cuerpo de la solicitud y la clave secreta del proyecto.
2. Aplique la función hash criptográfica SHA-1 a la string (cadena) obtenida en el primer paso.

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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 Pago del pedido realizado correctamente y Cancelación del pedido 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.

Si el servidor de Xsolla no ha recibido una respuesta al webhook Pago o al webhook Reembolso, ni ha recibido una respuesta con un código 5xx, los webhooks también se reenviarán con un intervalo de tiempo mayor. Se realiza un máximo de 12 intentos en 12 horas.

Si el servidor de Xsolla no ha recibido respuesta al webhook Validación del usuario o ha recibido una respuesta con un código 400 o 5xx, el webhook Validación del usuario no se reenvía. En este caso, el usuario ve un error y los webhooks Pago y Pago del pedido realizado correctamente no se envían.

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

Código	Mensaje
INVALID_USER	Usuario no válido
INVALID_PARAMETER	Parámetro no válido
INVALID_SIGNATURE	Firma no válida
INCORRECT_AMOUNT	Importe incorrecto
INCORRECT_INVOICE	Factura incorrecta

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook	Tipo de notificación	Descripción
Validación del usuario	user_validation	Se envía para comprobar si un usuario existe en el juego.
Búsqueda de usuario	user_search	Se envía para obtener información de usuario basada en el ID público del usuario.
Pago	payment	Se envía cuando un usuario realiza un pago.
Reembolso	refund	Se envía cuando un pago debe cancelarse por cualquier motivo.
Reembolso parcial	partial_refund	Se envía cuando un pago debe cancelarse parcialmente por cualquier motivo.
Transacción de AFS rechazada	afs_reject	Se envía cuando se rechaza una transacción durante una comprobación de AFS.
Lista de bloqueo de AFS rechazada	afs_black_list	Se envía cuando se actualiza la lista de bloqueo de AFS.
Suscripción creada	create_subscription	Se envía cuando un usuario crea una suscripción.
Suscripción actualizada	update_subscription	Se envía cuando se renueva o modifica una suscripción.
Suscripción cancelada	cancel_subscription	Se envía cuando se cancela una suscripción.
Suscripción con renovación suspendida	non_renewal_subscription	Se envía cuando el estado es de renovación suspendida.
Añadir cuenta de pago	payment_account_add	Se envía cuando un usuario añade o guarda una cuenta de pago.
Eliminar cuenta de pago	payment_account_remove	Se envía cuando un usuario elimina la cuenta de pago de las cuentas guardadas.
Validación del usuario en Web Shop	-	Se envía desde un sitio de Web Shop para comprobar si un usuario existe en el juego.
Personalización del catálogo en el lado del socio	partner_side_catalog	Se envía cuando un usuario interactúa con la tienda.
Pago del pedido realizado correctamente	order_paid	Se envía cuando se paga un pedido.
Cancelación del pedido	order_canceled	Se envía cuando se cancela un pedido.
Disputa	dispute	Se envía cuando se abre una nueva disputa.