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

Configuración de webhooks cuando se trabaja 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.
Buy Button	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	Para 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	Opcional	Para la 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	Opcional	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. Puede obtener más información en las instrucciones de para establecer webhooks para Digital Distribution Hub.

Si utiliza productos y soluciones que requieren webhooks, habilite 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 tanto, si no procesa uno de los webhooks, no se enviarán los posteriores. La lista de webhooks requeridos se muestra a continuación.

Para que una tienda dentro del juego funcione plenamente, hay que 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.
• Pago correcto del pedido (order_paid): se envía cuando se procesó correctamente un webhook Pago y contiene información sobre los artículos comprados y el ID de la transacción. Usa los datos del webhook para agregar artículos al usuario.
• Reembolso (refund): se envía cuando se cancela un pedido y contiene los datos del pago cancelado y los detalles de la transacción.
• Cancelación de pedido (order_canceled): se envía cuando se ha procesado correctamente un webhook Reembolso y contiene información sobre los artículos comprados y el ID de la transacción cancelada. Use 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 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. Abra su proyecto en Cuenta del editor.
2. Haga clic en Project settings en el menú lateral y vaya a la pestaña Webhooks.
3. 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.
4. 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.
5. Haga clic en Enable webhooks.

Para deshabilitar la recepción de webhooks:

1. Abra su proyecto en Cuenta del editor.
2. Haga clic en Project settings en el menú lateral y vaya a la pestaña Webhooks.
3. Haga clic en Disable webhooks.

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

Puede probar la recepción de los siguientes webhooks:

Nombre del webhook	Tipo de webhook
Validación de usuario	user_validation
Pago	payment
Cancelación del pedido	order_canceled
Pago del pedido realizado correctamente	order_paid

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

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

• 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 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. Introduzca cualquier valor en el campo Xsolla Order ID.
4. Seleccione el código (SKU) de los artículos de la lista desplegable e indique el importe. Puede elegir varios artículos del mismo tipo haciendo clic en + y agregándolos a una nueva línea.
5. Elija la moneda en la que se abonará el pedido.
6. Haga clic en Test.

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

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

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

Para realizar la prueba:

1. En la sección de pruebas, vaya a la pestaña Payments.
2. Rellene los campos requeridos:
   1. User ID: cuando realice la prueba, puede utilizar cualquier combinación de letras y dígitos.
   2. Public user ID: ID conocido por un usuario, p. ej., un correo electrónico o un alias. Este campo se muestra si el ID de usuario público está habilitado en su proyecto en la sección Pay Station > Settings > Additional settings.
   3. Currency: seleccione una moneda de la lista desplegable.
   4. Xsolla Invoice ID: ID de transacción en el lado de Xsolla. Al realizar una prueba, puede utilizar cualquier valor numérico.
   5. Amount: importe del pago. Al realizar pruebas, puede utilizar cualquier valor numérico.
   6. Invoice ID: ID de transacción en el lado de su juego. Al realizar pruebas, puede usar cualquier combinación de letras y dígitos. No es un parámetro obligatorio para que un pago sea aceptado, pero puede transmitirlo para vincular el ID de transacción de su lado con el ID de transacción en el lado de Xsolla.
3. Pulse en Test webhooks.

En la URL especificada, recibirá webhooks con los datos rellenados. Los resultados de las pruebas de cada webhook, tanto para un escenario satisfactorio como para un escenario fallido, se muestran bajo el botón Test webhooks. Si el ID público de usuario está habilitada en su proyecto, también podrá ver los resultados de una comprobación de búsqueda de usuario.

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

Cuando guarde la URL en el campo Webhook server, podrá ver la sección Advanced settings donde podrá conceder permisos para recibir información detallada en los webhooks. Para ello, establezca los respectivos selectores en la posición On. En la línea de cada permiso, puede ver la lista de webhooks afectados por 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.

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

• Validación de 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ónPay 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 no se recibió una respuesta para los webhooks Pago del pedido realizado correctamente y Cancelación del pedido o si se recibió una respuesta con un código "5xx", los webhooks se reenvían de acuerdo con la siguiente programación:

• 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 efectúan un máximo de 20 intentos de envío de webhooks en un periodo de 12 horas desde el primer intento. Si para el webhook Pago o el webhook Reembolso no se ha recibido una respuesta o si se ha recibido una respuesta con un código "5xx", los webhooks también se reenvían con un intervalo de tiempo mayor. Se realiza un máximo de 12 intentos en el plazo de 12 horas.

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

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.