Configurar 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

Si desea recibir notificaciones de eventos, implemente el control de webhooks:

• Payment: se envía cuando se paga un pedido y contiene los detalles de pago y los detalles de la transacción.
• Pago del pedido realizado correctamente: se envía cuando se ha procesado correctamente un webhook de Payment (Pago) y contiene información sobre los artículos comprados y del ID de la transacción.
• Refund (Reembolso): se envía cuando se cancela un pedido, y contiene los detalles de pago y los detalles de la transacción.
• Order cancellation (Cancelación del pedido): se envía cuando se ha procesado correctamente un webhook de Refund (Reembolso) y contiene información sobre los artículos comprados y el ID de la transacción cancelada.

• User validation (Validación del usuario): se envía en diferentes fases del proceso de pago para garantizar que el usuario está registrado en el juego. Contiene información sobre el usuario que compra la clave del juego.

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.

Si está usando un ID externo (ID de transacción en su sistema) y desea asociarlo con un ID de transacción en el lado de Xsolla o transmitir parámetros adicionales, implemente el webhook Transaction’s ID linking (Vincular el ID de la transacción).

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 Configuración del proyecto del menú lateral y vaya a la pestaña Webhooks.
3. En el campo Servidor de webhooks 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 Habilitar webhooks.

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

Puede probar la recepción de los siguientes webhooks:

Si los webhooks están establecidos correctamente, se muestra un bloque de prueba de webhooks debajo del bloque de configuración de webhooks.

• Store
• Payments

Nota

Para las pruebas, debe crear al menos un paquete de claves del juego.

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

• Pago del pedido realizado correctamente (order_paid)
• Cancelación del pedido (order_canceled)

1. En el bloque de pruebas del webhook, vaya a la pestaña Store.
2. En el menú desplegable, seleccione Game keys. Si el paquete de claves del juego no está establecido en Cuenta del editor, se mostrará uno de los siguientes botones:
   • Connect — si el módulo Game keys no está conectado
   • Configure — si ha conectado el módulo previamente, pero no ha completado la configuración

3. Introduzca cualquier valor en el campo Xsolla Order ID.
4. Seleccione el paquete de claves del juego de la lista desplegable.
5. Especifique las plataformas de publicación del juego.
6. Especifique un valor arbitrario de la clave del juego en el campo Amount.
7. Elija la moneda en la que se pagará el pedido.
8. Haga clic en Test.

Los webhooks Successful payment of the order y Order cancellation con los datos especificados se envían a la URL proporcionada. Los resultados de la prueba de cada tipo de webhook se muestran debajo de los botones de Test.

Nota

Si aparece un mensaje de error en el bloque de pruebas indicando que la prueba no se ha superado, compruebe la configuración de la respuesta del webhook en su agente de escucha de webhooks. La información sobre estos errores está disponible en los resultados de la prueba.

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

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

Para probar:

1. En la sección de pruebas, vaya a la pestaña Payments.
2. Rellene los campos necesarios:
   • ID de usuario: al realizar pruebas, puede usar cualquier combinación de letras y dígitos.
   • 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 > Additional settings.
   • Moneda: seleccione una moneda de la lista desplegable.
   • ID de factura de Xsolla: ID de la transacción en el lado de Xsolla. Al hacer pruebas, puede utilizar cualquier valor numérico.
   • Importe: importe del pago. Al hacer pruebas, puede utilizar cualquier valor numérico.
   • 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.
3. Pulse en Test webhooks.

En la URL especificada, recibirá webhooks con los datos introducidos. 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 de usuario público está habilitado en su proyecto, también verá los resultados de una consulta de búsqueda de usuarios.

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

Cuando guarde la URL en el campo Webhook server, podrá ver la sección Advanced settings en la que podrá otorgar permisos para recibir información detallada en los webhooks. Para ello, cambie los respectivos conmutadores a la posición On. En la línea de cada permiso, puede ver la lista de webhooks afectados por los ajustes.

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 no se recibió una respuesta para los webhooks Successful payment of the order y Order cancellation o si se ha recibido 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
• 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 para el webhook Pago no se recibió una respuesta o si se recibió 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 no se recibió una respuesta para el webhook Validación del usuario o si se recibió 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 Pago y Successful payment of the order.