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?
Pagos	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	Receiving information about creation, update, or cancellation of a subscription. Alternatively, you can request information via the 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. User authentication, if you use authentication via user ID. Alternatively, you can use user authentication via 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. Refer to the documentation for detailed information on setting up webhooks for the Digital Distribution Hub.

If you use products and solutions that require working with webhooks, enable and test the webhooks in your Publisher Account and set up their processing. When specific events occur, webhooks are sent sequentially. Therefore, if you do not process one of the webhooks, subsequent webhooks will not be sent. The list of required webhooks is presented below.

2 webhook sending options have been set up on Xsolla’s side when purchasing and returning items on the site — information with payment and transaction data and information about purchased items can come separately or can be combined into one webhook.

Receiving information in combined webhooks:

If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment of the order (order_paid) and Order cancellation (order_canceled) webhooks. In this case, you do not need to process the Payment (payment) and Refund (refund) webhooks.

Receiving information in separate webhooks:

If you registered in Publisher Account on or before January 22, 2025, you receive the following webhooks:

• Payment (payment) and Refund (refund) with information about payment data and transaction details.
• Successful payment of the order (order_paid) and Order cancellation (order_canceled) with information about purchased items.

You need to process all incoming webhooks. To switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to csm@xsolla.com.

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks.

If you receive combined webhooks:

Webhook name and type	Descripción
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Game services > Combined webhooks > Successful payment of the order (order_paid)	It contains payment data, transaction details, and information about purchased items. Use the data from the webhook to add items to the user.
Game services > Combined webhooks > Order cancellation (order_canceled)	It contains data of the canceled payment, transaction details, and information about purchased items. Use the data from the webhook to remove the purchased items.

If you receive separate webhooks:

Webhook name and type	Descripción
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Payments > Payment (payment)	It contains payment data and transaction details.
Game services > Separate webhooks > Successful payment of the order (order_paid)	It contains information about purchased items and the transaction details. Use the data from the webhook to add items to the user.
Payments > Refund (refund)	It contains payment data and transaction details.
Game services > Separate webhooks > Order cancellation (order_canceled)	It contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items.

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 de 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. In the project in Publisher Account go to Project Settings > Webhooks section.
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. In the project in Publisher Account go to Project Settings > Webhooks section.
2. Haga clic en Disable webhooks.

For the webhooks in the Payment and store section, advanced settings are available. They will automatically appear under the General settings block after you click the Get webhooks button.

In this section, you can set up the receipt of additional information in webhooks. To do this, set the corresponding switches to the active position. The line of each permission indicates the webhooks that will be affected by changing the settings.

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

The testing section in the Publisher Account varies depending on the webhook receiving option.

If you receive combined webhooks:

Tab name for webhook testing	Webhook name and type
Payments and store	User validation > User validation (user_validation)
	Game services > Combined webhooks > Successful payment of the order (order_paid)
	Game services > Combined webhooks > Order cancellation (order_canceled)
Subscriptions	User validation > User validation (user_validation)
	Payments > Payment (payment)

If you receive separate webhooks:

Tab name for webhook testing	Webhook name and type
Store	Game services > Separate webhooks > Successful payment of the order (order_paid)
	Game services > Separate webhooks > Order cancellation (order_canceled)
Payments	User validation > User validation (user_validation)
	Payments > Payment (payment)
Subscriptions	User validation > User validation (user_validation)
	Payments > Payment (payment)

The process of testing for the scenario with combined webhooks is described below.

In the Payment and store tab, you can test the following webhooks:

• Validación de usuario (user_validation)
• Pago del pedido realizado correctamente (order_paid)
• Cancelación del pedido (order_canceled)

Para realizar la prueba:

1. In the webhooks testing section, go to the Payment and store tab.

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. Fill in the necessary fields:

   1. Select the items’ SKU from the drop-down list and indicate the amount. You can choose multiple items of the same type by clicking + and adding them in a new line.
   2. User ID — when testing, you can use any combination of letters and digits.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings.
   4. Enter any value in the Xsolla Order ID field.
   5. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   6. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Currency — select a currency from the drop-down list.

4. Click Test webhooks.

User validation, Successful payment of the order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhooks button.

If public user ID is enabled in your project, you will also see the results of a user search check.

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 de usuario (user_validation)
• Pago (payment)

To test:

1. In the testing section, go to the Subscriptions tab.
2. Fill in the necessary fields:
   1. User ID — when testing, you can use any combination of letters and digits.
   2. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings > Additional settings section.
   4. Currency — select a currency from the drop- down list.
   5. Plan ID — a subscription plan. Choose a plan from the drop-down list.
   6. Subscription product — choose a product from the drop-down list (optional).
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   9. Trial period. To test the purc hase of a subscription without a trial period or to test the renewal of a subscription, specify the value 0.
3. Click 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.

If the Xsolla server did not receive a response to Successful payment of the order and Order cancellation webhooks or received a response with a 5xx code, the webhooks are resent according to the following schedule:

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

Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt. If the Xsolla server did not receive a response to Payment webhook or the Refund webhook, or received a response with a 5xx code, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.

If the Xsolla server did not receive a response to the User validation webhook or received a response with a code of 400 or 5xx, the User validation webhook is not resent. In this case, the user sees an error and the Payment and Successful payment of the order webhooks are not sent.

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