Establecer webhooks

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 que se transmiten los datos del evento, a su aplicación. Generalmente, se trata de una solicitud POST en formato JSON.

Ejemplos de evento:

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

Lista de webhooks

Para cambiar a la nueva opción con recepción de webhooks combinados, contacte con sus gestores del éxito del cliente o envíe un correo electrónico a [email protected].

Para que la tienda en el juego y el sistema de gestión de pagos funcionen a pleno rendimiento, es necesario implementar el procesamiento de los principales webhooks:

• Si recibe webhooks combinados
• Si recibe webhooks por separado

Nombre del webhook	Descripción
Validación del usuario > Validación del usuario (user_validation)	Se envían en distintas fases del proceso de pago para garantizar que el usuario esté registrado en el juego.
Servicios del juego > Webhooks combinados > Successful payment for order (order_paid)	Contiene datos de pago, detalles de la transacción e información sobre los artículos comprados. Emplee los datos del webhook para agregar artículos al usuario.
Servicios del 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. Emplee los datos del webhook para eliminar los artículos comprados.

El siguiente esquema muestra el proceso de compra y de devolución de artículos utilizando webhooks combinados.

Nombre del webhook	Descripción
Validación del usuario > Validación del usuario (user_validation)	Se envían en distintas fases del proceso de pago para garantizar que el usuario esté registrado en el juego.
Pagos > Pago (payment)	Contiene datos de pago y detalles de la transacción.
Servicios del juego > Webhooks por separado > Successful payment for order (order_paid)	Contiene información sobre los artículos comprados y los detalles de la transacción. Emplee los datos del webhook para agregar artículos al usuario.
Pagos > Reembolso (refund)	Contiene datos de pago y detalles de la transacción.
Servicios del juego > Webhooks por separado > Cancelación del pedido (order_canceled)	Contiene información sobre los artículos comprados y el ID de la transacción cancelada. Emplee los datos del webhook para eliminar los artículos comprados.

El siguiente esquema muestra el proceso de compra y de devolución de artículos utilizando webhooks por separado.

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

Establecer webhooks en Cuenta del editor

Para habilitar la recepción de webhooks:

1. Abra su proyecto en Cuenta del editor.
2. Haga clic en Project settings del menú lateral y vaya a la pestaña Webhooks.
3. En el campo Webhook server especifique la URL de su servidor donde quiere recibir los 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 quiere generar una nueva clave secreta, haga clic en el icono de actualización.
5. Haga clic en Enable webhooks.

Al guardar la URL en el campo Webhook server, verá la sección Advanced settings en la que puede dar permisos para recibir información detallada en los webhooks. Para ello, active las opciones correspondientes. En la línea de cada permiso, verá la lista de webhooks a los que afecta la configuración.

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

Probar los webhooks en Cuenta del editor

Si los webhooks están establecidos correctamente, se muestra un bloque de prueba de webhooks debajo del bloque 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 de webhooks.

Más abajo se describe el proceso de pruebas para el escenario en el que se reciben webhooks combinados.

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

• User validation (user_validation)
• Successful payment for order (order_paid)
• Order cancellation (order_canceled)

1. En la sección de pruebas de webhooks, vaya a la pestaña Pagos y tienda.
2. En el menú desplegable, seleccione el tipo de artículo. Si el tipo de artículo seleccionado no está establecido en Cuenta del editor, pulse en:
   • Conectar: si el módulo con artículos de este tipo no está conectado
   • Configurar: si ha conectado el módulo previamente, pero no ha finalizado la configuración
   Al pulsar el botón, será redirigido a la sección de Cuenta del editor correspondiente al tipo de artículo seleccionado. Una vez creado el artículo, vuelva a la sección de pruebas de webhooks y proceda al paso siguiente.
3. Rellene los campos necesarios:
   1. Seleccione el código (SKU) de los artículos que figuran en la lista desplegable e indique el importe. Puede elegir varios artículos del mismo tipo pulsando en + y agregándolos a una nueva línea.
   2. ID de usuario: al realizar pruebas, puede usar cualquier combinación de letras y dígitos.
   3. ID pública del usuario: 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.
   4. Introduzca cualquier valor en el campo ID del pedido de Xsolla.
   5. ID de factura de Xsolla: ID de la transacción en el lado de Xsolla. Al hacer pruebas, puede utilizar cualquier valor numérico.
   6. ID de factura: ID de transacción en el lado de su juego. Durante las pruebas, puede usar cualquier combinación de letras y dígitos. No es un parámetro requerido para un pago aceptado, pero puede transmitirlo para vincular el ID de transacción de su lado con el ID de transacción del lado de Xsolla.
   7. Importe: importe del pago. Al hacer pruebas, puede utilizar cualquier valor numérico.
   8. Moneda: seleccione una moneda de la lista desplegable.
4. Haga clic en Probar webhooks.

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

Agente de escucha de webhooks

El agente de escucha de webhooks 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.

Generación de firma

Cuando reciba un webhook, se debe garantizar la seguridad de la transmisión de datos. Para conseguirlo, 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 cadena obtenida en el primer paso.

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 correcta.
• Código HTTP 400 con descripción del problema si no se ha encontrado el usuario especificado o se ha transmitido una firma no válida.

Su controlador de webhook también puede devolver un código 5xx en caso de problemas temporales en su servidor.

Si el servidor de Xsolla no recibe una respuesta para los webhooks Successful payment for order y Order cancellation o si recibe una respuesta con un código 5xx, los webhooks se reenvían con arreglo al siguiente esquema temporal:

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

Se realizan 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 recibe una respuesta para los webhooks Pago o Reembolso o si recibe una respuesta con un código 5xx, los webhooks también se reenvían con un intervalo mayor. Se realiza un máximo de 12 intentos en 12 horas.

Si el servidor de Xsolla no recibe una respuesta para los webhooks Validación del usuario o si recibe una respuesta con un código 400 o 5xx, el webhook Validación del usuario no se reenvía.

En este caso, se muestra un error al usuario y no se envían los webhooks Payment y Successful payment of the order.

Configurar la información de los artículos en los webhooks

Puede configurar qué datos de los artículos se incluyen en los webhooks Pago del pedido realizado correctamente y Cancelación del pedido a través de la matriz de items.

Activar la inclusión de parámetros adicionales

Active la inclusión de parámetros adicionales que indiquen:

• si el artículo es gratuito (is_free)
• si el artículo es una bonificación (is_bonus)
• si el artículo forma parte de un lote (is_bundle_content)

Para recibir estos parámetros, debe cambiar sus webhooks a la versión 2 mediante la llamada a la API Actualizar la información sobre la configuración de webhooks. En la versión 1 (predeterminada), estos parámetros no están disponibles.

Ejemplo de matriz de artículos con parámetros adicionales:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      },
14      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

Desactivar la inclusión del contenido del lote

Por defecto, los webhooks incluyen todos los artículos del lote como una lista de artículos individuales. Puede configurar el webhook para que solo incluya el lote en sí, sin detallar su contenido.

En este caso, los artículos incluidos en el lote no se incluyen en la matriz de items. En la matriz que se muestra arriba, el artículo con el SKU com.xsolla.gold_1, que forma parte del lote, está excluido.

Ejemplo de matriz de artículos cuando el contenido del lote está desactivado:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ],

Para desactivar la inclusión del contenido del lote, contacte con su gestor del éxito del cliente o envíe un correo electrónico a [email protected].