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.
Se han configurado 2 opciones de recepción de webhooks en el lado de Xsolla cuando se compran y devuelven artículos en el sitio web: la información con los datos de pago y la transacción, y la información sobre los artículos comprados pueden llegar por separado o combinarse en un solo webhook.
Más información sobre las opciones de recepción de webhooks
Recibir información en webhooks combinados:
Si ha creado un proyecto en Cuenta del editor después del 22 de enero de 2025, recibirá toda la información en los webhooks Pago del pedido realizado correctamente (order_paid
) y Cancelación del pedido (order_canceled
). En este caso, no tiene que procesar los webhooks Pago (payment
) y Reembolso (refund
).
Recibir información en webhooks por separado:
Si ha creado un proyecto en Cuenta del editor antes del (o ese día) 22 de enero de 2025, recibirá toda la información en los webhooks:
- Pago (
payment
) y Reembolso (refund
) con información sobre los datos de pago y los detalles de la transacción. - Pago del pedido realizado correctamente (
order_paid
) y Cancelación del pedido (order_canceled
) con información sobre los artículos comprados.
Debe procesar todos los webhooks entrantes.
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 csm@xsolla.com.
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 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:
- Abra su proyecto en Cuenta del editor.
- Haga clic en Configuración del proyecto del menú lateral y vaya a la pestaña Webhooks.
- 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.
- 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.
- Haga clic en Habilitar webhooks.
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.
- Abra su proyecto en Cuenta del editor.
- Haga clic en Project settings en el menú lateral y acceda a la pestaña Webhooks.
- 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 Pagos y tienda, puede probar los siguientes webhooks:
- Validación del usuario (
user_validation
) - Pago del pedido realizado correctamente (
order_paid
) - Cancelación del pedido (
order_canceled
)
- En la sección de pruebas de webhooks, vaya a la pestaña Pagos y tienda.
- En el menú desplegable, seleccione Claves del juego. Si los paquetes de claves del juego no están establecidos en Cuenta del editor, se mostrará uno de los siguientes botones:
- Conectar: si el módulo Claves del juego no está conectado
- Configurar: si conectó el módulo previamente, pero no ha completado la configuración
- Rellene los campos necesarios:
- Introduzca cualquier valor en el campoID del pedido de Xsolla.
- Seleccione el paquete de claves del juego de la lista desplegable.
- Especifique las plataformas de publicación del juego.
- 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.
- ID de factura de Xsolla: ID de la transacción en el lado de Xsolla. Al hacer pruebas, puede utilizar cualquier valor numérico.
- ID de factura: ID de la 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.
- Importe: importe del pago. Al hacer pruebas, puede utilizar cualquier valor numérico.
- Moneda: seleccione una moneda de la lista desplegable.
- 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:
- Concatene el JSON del cuerpo de la solicitud y la clave secreta del proyecto.
- 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
o204
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.
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 Pago y Successful payment of the order.
¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.