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 que funcione plenamente una tienda en el juego, es necesario implementar el procesamiento de los principales 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 aceptado: se envía cuando se ha procesado correctamente un webhook Payment, y contiene información sobre los artículos comprados y el ID de la transacción. Utilice los datos del webhook para agregar artículos al usuario.
  • Refund (Reembolso): se envía cuando se cancela un pedido, y contiene los detalles de pago y los detalles de la transacción.
  • Cancelación del pedido: se envía cuando se ha procesado correctamente un webhook de Refund y contiene información sobre los artículos comprados y el ID de la transacción cancelada. Utilice los datos del webhook para eliminar los artículos comprados.
  • Validación del usuario: se envía en distintas fases del proceso de pago para garantizar que el usuario esté registrado en el juego.

Abajo hay un esquema de compra y devolución de productos en el sitio web utilizando los webhooks de esta lista.

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.

Nota
Para recibir pagos reales, sólo necesita implementar el procesamiento de los webhooks Payment, Successful payment of the order y User validation, así como firmar el acuerdo de licencia.
Nota
Puede utilizar la integración con PlayFab para recibir información de pago y de cancelación de pedidos en lugar de utilizar webhooks.

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 desea 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 desea generar una nueva clave secreta, pulse en el icono de actualización.
  5. Haga clic en Enable webhooks.

Nota
Para probar los webhooks, también puede seleccionar cualquier sitio web específico, como webhook.site, o una plataforma, como ngrok.
Aviso
No puede enviar webhooks simultáneamente a varias URL. Lo que sí puede hacer en Cuenta del editor es especificar primero una URL para pruebas y, luego, sustituirla por la real.
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 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:

Nombre del webhookTipo de webhook
Validación del usuariouser_validation
Pagopayment
Order cancellationorder_canceled
Successful payment of the orderorder_paid

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

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.

Nota
La lista completa y el mecanismo de los webhooks, junto con ejemplos pormenorizados de su procesamiento, se describen en la documentación de webhooks.
¿Te ha resultado útil este artículo?
¡Gracias!
¿Hay algo en lo que podamos mejorar? Mensaje
Lo sentimos
Por favor, cuéntanos por qué no te ha resultado útil este artículo. Mensaje
¡Gracias por tu mensaje!
Nos ayudará a mejorar tu experiencia.
Última actualización: 11 de Septiembre de 2024

¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.

Informar de un problema
Nos esforzamos por ofrecer contenido de calidad. Tus comentarios nos ayudan a mejorar.
Déjanos tu correo electrónico para que te podamos responder
¡Gracias por tu mensaje!