Notificaciones de Webhook

En lugar de monitorear manualmente todos los eventos en tu juego y las solicitudes de los usuarios, puedes configurar webhooks para recibir notificaciones en tiempo real en una herramienta de mensajería de terceros o en tu punto final personalizado que puede recibir solicitudes HTTP. Esto te ayuda a automatizar tu flujo de trabajo de gestión de notificaciones para reducir el esfuerzo manual en el manejo de notificaciones.

Flujo de trabajo de Webhook

Los webhooks envían notificaciones o datos en tiempo real entre dos aplicaciones o servicios diferentes, como Roblox y una herramienta de mensajería de terceros. A diferencia de las API tradicionales, que requieren que configures una aplicación cliente para enviar solicitudes a un servidor y recibir datos, los webhooks envían datos a tu punto final de cliente tan pronto como ocurre un evento. Son útiles para automatizar flujos de trabajo entre Roblox y aplicaciones de terceros que utilizas para colaborar con tu equipo, ya que permiten compartir y procesar datos en tiempo real.

Una vez que configures un webhook, cada vez que ocurra un evento objetivo, Roblox envía una solicitud a la URL del webhook que proporcionas. La URL del webhook redirige la solicitud a tu aplicación receptora o punto final personalizado, que puede tomar medidas en función de los datos incluidos en el contenido de la carga útil del webhook. Esto podría incluir eliminar datos para cumplir con el RTBF, enviar una confirmación al usuario o desencadenar otro evento.

Disparadores admitidos

Roblox actualmente admite los siguientes disparadores de eventos.

Suscripción

• Suscripción Reanudada - Cuando un usuario reanuda una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
• Suscripción Renovada - Cuando un usuario renueva una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
• Suscripción Reembolsada - Cuando un usuario recibe un reembolso por su suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
• Suscripción Comprada - Cuando un usuario compra una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
• Suscripción Cancelada - Cuando un usuario cancela una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor, así como el motivo dado para la cancelación.

Para más información sobre los eventos de suscripción y sus campos, consulta la referencia de Suscripción.

Cumplimiento

• Derecho a la Eliminación / Solicitud de Eliminación - Cuando un usuario ejerce su derecho a que su información personal sea eliminada permanentemente bajo las regulaciones globales aplicables de protección de datos y privacidad. Más información puede encontrarse en RTBF y Creadores.

Comercio

• Pedido de Producto de Comercio Reembolsado - Cuando un usuario ha recibido un reembolso por su pedido de producto de comercio, o el pedido fue cancelado.
• Pedido de Producto de Comercio Pagado - Cuando un usuario ha pagado por su pedido de producto de comercio. Ten en cuenta que son posibles eventos de webhook duplicados, así que debes desduplicar eventos utilizando el ID de pedido de comercio único.

Configurar webhooks en el Panel del Creador

Para recibir notificaciones a través de webhooks, debes configurar un webhook que se suscriba a ciertos eventos para activar notificaciones. Para los juegos de propiedad grupal, solo los propietarios del grupo pueden configurar y recibir notificaciones de webhook.

Para configurar un webhook:

1. Selecciona tu experiencia en Creator Hub.

2. En Configurar, selecciona Webhooks y haz clic en Agregar Webhook.

   La URL del webhook proviene de tu proveedor. Por ejemplo, una URL de Slack probablemente luzca así:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Ingresa tu URL de webhook y un nombre.

4. (Opcional) Incluye un secreto, que ayuda a garantizar que las notificaciones que recibes provienen de Roblox. Para más información, consulta Verificar seguridad del webhook.

5. Elige una o más opciones de la lista de disparadores admitidos de eventos para los cuales deseas recibir notificaciones.

6. (Opcional) Utiliza el botón de Respuesta de Prueba para verificar si tu servicio puede recibir una solicitud de muestra.

7. Haz clic en Guardar Cambios.

Configurar URLs de webhooks

Puedes configurar un punto final de servicio HTTP personalizado como tu URL de webhook, siempre que cumpla con los siguientes requisitos:

• Debe ser accesible públicamente para manejar solicitudes.
• Puede manejar solicitudes POST.
• Puede responder a la solicitud con una respuesta 2XX dentro de 5 segundos.
• Puede manejar solicitudes HTTPS.

Cuando tu punto final recibe una solicitud POST, debe ser capaz de:

• Extraer los detalles requeridos sobre la notificación del cuerpo del mensaje POST.
• Leer el cuerpo del mensaje POST con los detalles genéricos sobre la notificación y los detalles específicos relacionados con el tipo de evento sobre la notificación.

Para más información sobre el esquema de las solicitudes POST a manejar, consulta el Esquema de Carga Útil.

Política de reintento de falla de entrega

Cuando una notificación de webhook no logra llegar a tu URL especificada debido a errores como la indisponibilidad del punto final, Roblox intenta enviar el mensaje a la URL configurada 5 veces utilizando un tamaño de ventana fijo. Si la notificación sigue sin entregarse después de 5 intentos, Roblox deja de intentar enviar la notificación y supone que la URL ya no es válida. En esta situación, debes actualizar la configuración de tu webhook con una nueva URL que sea accesible y capaz de recibir notificaciones. Para solucionar problemas y confirmar que tu URL de webhook puede recibir notificaciones con éxito, consulta Probar webhooks.

Requerimientos de terceros

Las herramientas de terceros generalmente tienen sus propios requisitos para webhooks que debes seguir al configurar tu URL de webhook. Puedes encontrar estos requisitos buscando la palabra clave "webhook" en el sitio de soporte o en la documentación de la herramienta objetivo. Para las herramientas de terceros admitidas, consulta lo siguiente:

• Centro de Ayuda de Discord
• Referencia de API de Slack

Probar webhooks

Puedes probar si el webhook que has configurado puede recibir notificaciones correctamente en el Panel del Creador:

1. Navega a la página de configuración de Webhooks.
2. Selecciona el webhook que deseas probar de la lista de webhooks configurados.
3. Haz clic en el ícono de lápiz junto al webhook objetivo.
4. Haz clic en el botón de Respuesta de Prueba.

El sistema envía un evento SampleNotification, que incluye el ID de Usuario del usuario que activó la notificación, como se muestra aquí:

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

Si estás integrando tu webhook con un servicio de terceros, puedes probarlo utilizando la URL de terceros para confirmar que el servicio puede recibir notificaciones de tu webhook con éxito. Si proporcionas un secreto al configurar el webhook, también genera una roblox-signature que puedes usar para probar la lógica de roblox-signature.

Verificar la seguridad del webhook

Después de configurar tu servidor para recibir cargas útiles, comienza a escuchar cualquier carga útil enviada al punto final. Si configuraste un secreto al configurar tu webhook, Roblox envía una roblox-signature en cada notificación de webhook para asegurarse de que la solicitud realmente provino de Roblox. La firma está en el encabezado de la carga útil para puntos finales personalizados y en el pie para servidores de terceros.

t=<timestamp>,v1=<signature>

Si no configuraste un secreto para tu webhook, la firma solo contiene la marca de tiempo de cuándo se envió la notificación:

t=<timestamp>

Para verificar una firma:

1. Extrae los valores de timestamp y signature. Todas las firmas para webhooks con secretos comparten el mismo formato como una cadena CSV con estos dos valores seguidos de los prefijos:

   • t: La marca de tiempo de cuándo se envió la notificación.
   • v1: El valor de la firma generada utilizando el secreto proporcionado por la configuración del Panel del Creador.

2. Re-crea la cadena base de roblox-signature concatenando:

   1. La marca de tiempo como una cadena.
   2. El carácter de punto ..
   3. La cadena JSON del cuerpo de la solicitud.

3. Calcula un código de autenticación de mensaje basado en hash (HMAC) con la función hash SHA256 usando el secreto que definiste durante la configuración como la clave y la cadena base que generaste a través del paso 2 como el mensaje. Convierte el resultado a formato Base64 para obtener la firma esperada.

4. Comparar el valor de la firma extraída con la firma esperada. Si generaste la firma correctamente, el valor debería ser el mismo.

5. (Opcional) Para prevenir ataques de repetición, un tipo de ataque cibernético donde los atacantes interceptan y reenvían datos para obtener acceso no autorizado o realizar acciones maliciosas, es útil comparar el valor de la marca de tiempo extraída con la marca de tiempo actual y asegurarse de que se encuentre dentro de un límite de tiempo razonable. Por ejemplo, una ventana de 10 minutos suele ser un buen límite de tiempo razonable.

Esquema de carga útil

Cuando se activa el evento objetivo de tu webhook, se envía una solicitud a tu URL de webhook, incluyendo información sobre el evento en la carga útil. Todas las cargas útiles de las solicitudes comparten el mismo esquema que consiste en campos fijos y variables. Esto asegura que los datos transmitidos en la carga útil estén estructurados y sean consistentes, lo que facilita el procesamiento y uso de los datos por parte de la aplicación receptora.

Los campos del esquema de carga útil fijos pueden ayudar a mantener la consistencia en todas las solicitudes de webhook, con los siguientes campos disponibles:

1. NotificationId (string): Un identificador único para cada notificación enviada. Si se recibe el mismo NotificationId dos veces, se considera un duplicado.
2. EventType (string): Indica el tipo de evento para el cual se activó la notificación.
3. EventTime (string): La marca de tiempo de cuándo se activó el evento.

Los campos del esquema de carga útil variables proporcionan flexibilidad para que los webhooks se adapten a varios tipos de eventos, que incluyen:

1. EventPayload (object): Contiene información específica sobre el EventType que activó el webhook. La estructura del esquema de EventPayload varía según el tipo de evento.

El siguiente ejemplo muestra el esquema de carga útil del evento Solicitud de Derecho a la Eliminación:

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Manejar notificaciones

Si almacenas Información Personalmente Identificable (PII) de tus usuarios, como sus IDs de Usuario, deberías evaluar la solicitud a la luz de tus obligaciones legales. Más información puede encontrarse en RTBF y Creadores. Puedes crear un bot para manejar las notificaciones de webhook y ayudar a automatizar la eliminación de datos, siempre que almacenes PII en un almacén de datos. Consulta Automatización de Eliminación de Solicitudes de Derecho a la Eliminación para un ejemplo sobre cómo crear un bot dentro de Discord que use la API de Open Cloud para almacenes de datos para eliminar datos PII como una solución de automatización. Este ejemplo puede adaptarse para manejar otras notificaciones, como eventos de suscripción.

Si utilizas un punto final personalizado como tu servidor de webhook en lugar de una herramienta de terceros, puedes extraer los datos sujetos a eliminación de la carga útil del webhook y construir tu propia solución de automatización. El siguiente ejemplo de código es un ejemplo de un servidor que tiene prevención contra ataques de repetición al verificar la marca de tiempo y que la solicitud proviene de Roblox:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // Esto puede configurarse como una variable de entorno

let app = express();
app.use(express.json());

app.all('/*', function (req, res) {
   console.log('Nueva solicitud recibida');

   // Extraer la marca de tiempo y la firma del encabezado
   const signatureHeader = req.headers['roblox-signature'].split(',');
   const timestamp = signatureHeader.find(e => e.startsWith('t=')).substring(2);
   const signature = signatureHeader.find(e => e.startsWith('v1=')).substring(3);

   // Asegurar que la solicitud venga dentro de una ventana de 300 segundos para prevenir ataques de repetición
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Solicitud Expirada');
   }

   // Validar firma
   const message = `${timestamp}.${JSON.stringify(req.body)}`;
   const hmac = crypto.createHmac('sha256', secret);
   const calculatedSignature = hmac.update(message).digest('base64');

   if (signature !== calculatedSignature) {
      return res.status(401).send('Solicitud No Autorizada');
   }

   // Tu lógica para manejar la carga útil
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

   if (eventType === 'RightToErasureRequest'){
      const userId = payloadBody['EventPayload']['UserId'];
      const gameIds = payloadBody['EventPayload']['GameIds'];

      console.log(`Datos de carga: UserId=${userId} y GameIds=${gameIds}`);
      // Si almacenas PII en los almacenes de datos, usa el UserId y los GameIds para eliminar la información de los almacenes de datos.
   }

   return res.json({ message: 'Mensaje procesado con éxito' });
});

app.listen(8080, function () {
   console.log('Servidor iniciado');
});