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

Para vender claves del juego, no es necesaria la validación del usuario ni acreditar los artículos. Puede conectar webhooks si desea recibir información sobre eventos, como el pago o la cancelación de pedidos.

Si conecta webhooks, es fundamental procesar todos los webhooks requeridos entrantes.

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:

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

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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. En su proyecto, en Cuenta del editor, vaya a la sección Settings > Webhooks.
2. En el campo Webhook server, especifique la URL de su servidor donde desea recibir los 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 quiere generar una nueva clave secreta, haga clic en el icono de actualización.
4. 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. En su proyecto, en Cuenta del editor, vaya a la sección Settings > Webhooks.
2. Haga clic en Disable webhooks.

Probar los webhooks en Cuenta del editor

Cuando habilite los webhooks en su proyecto, aparecerá una sección para probarlos en Cuenta del editor, debajo de la configuración avanzada.

Puede probar los siguientes webhooks:

Para probar webhooks:

1. En la sección de pruebas de webhooks, vaya a la pestaña Pagos y tienda.
2. En el menú desplegable, seleccione Game keys. Si los paquetes de claves del juego no están configurados en su proyecto, verá un botón para acceder a su configuración.
3. Rellene los campos necesarios:
   • Xsolla order ID: ID del pedido en el lado de Xsolla. Mientras se realizan pruebas, puede usar cualquier valor numérico.
   • Xsolla Invoice ID: El ID de la transacción en el lado de Xsolla. Durante las pruebas, puede usar cualquier valor numérico.
   • Items: Artículos sobre los que desea recibir información en el webhook. Seleccione el SKU de los artículos en la lista desplegable e indique la cantidad. Puede elegir varios artículos del mismo tipo pulsando en + y añadiéndolos en una nueva fila.
   • User ID: Cuando realice pruebas, puede usar cualquier combinación de letras y dígitos.
   • Invoice ID: 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 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 de Xsolla.
   • Amount: Importe del pago. Mientras realiza pruebas, puede utilizar cualquier valor numérico.
   • Currency: Seleccione una moneda de la lista desplegable.
4. Haga clic en Probar webhooks.

Los webhooks Successful payment for order, Order cancellation y User validation con los datos especificados se envían a la URL facilitada. Los resultados de las pruebas de cada tipo de webhook se muestran debajo del botón Test webhook. Para cada webhook, tiene que configurar el procesamiento de ambos escenarios: el satisfactorio y el que tiene un error.

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

La lógica de reintento para los webhooks Payment y Refund viene descrita en la página respectiva de cada webhook.

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.