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 pueda 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 para recibir datos, los webhooks envían datos a tu punto final 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 el intercambio y procesamiento de datos en tiempo real.

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

Disparadores soportados

Roblox actualmente admite los siguientes disparadores de eventos.

Suscripción

• Suscripción Reinscrita - Cuando un usuario se reinscribe a 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 la razón dada 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 de protección de datos y privacidad aplicables. Más información se puede encontrar en RTBF y Creadores.

Comercio

• Orden de Producto Comercial Reembolsada - Cuando un usuario ha recibido un reembolso por su orden de producto comercial, o la orden fue cancelada.
• Orden de Producto Comercial Pagada - Cuando un usuario ha pagado por su orden de producto comercial. Ten en cuenta que es posible que ocurran eventos de webhook duplicados, por lo que debes deduplicar eventos utilizando el ID de orden de comercio único.

Configurar webhooks en el Panel de Creadores

Para recibir notificaciones a través de webhooks, necesitas configurar un webhook que se suscriba a ciertos eventos para activar notificaciones. Para juegos de propiedad de grupos, 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 se vea 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 la seguridad del webhook.

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

6. OPCIONAL

   Usa el botón Probar Respuesta para verificar si tu servicio puede recibir una solicitud de muestra.

7. Haz clic en Guardar Cambios.

Configurar URLs de webhook

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 detalles específicos relacionados con el tipo de evento en 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 fallo de entrega

Cuando una notificación de webhook no puede 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 aún no se entrega después de 5 intentos, Roblox deja de intentar enviar la notificación y asume que la URL ya no es válida. En esta situación, necesitas actualizar tu configuración de 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.

Requisitos de terceros

Las herramientas de terceros generalmente tienen sus propios requisitos para los 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 documentación de la herramienta objetivo. Para las herramientas de terceros soportadas, 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 con éxito en el Panel de Creadores:

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 Probar Respuesta.

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 estableciste un secreto al configurar tu webhook, Roblox envía una roblox-signature en cada notificación de webhook para garantizar 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 de página para servidores de terceros.

t=<timestamp>,v1=<signature>

Si no estableciste 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 marca de tiempo y firma. Todas las firmas para webhooks con secretos comparten el mismo formato como una cadena CSV con estos dos valores seguidos por los prefijos:

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

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 utilizando el secreto que definiste durante la configuración como la clave y la cadena base que generaste en el paso 2 como el mensaje. Convierte el resultado a formato Base64 para obtener la firma esperada.

4. Compara 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 esté 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, 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, facilitando el procesamiento y uso de los datos por parte de la aplicación receptora.

Los campos de 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 de 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 de 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 cualquier Información Personalmente Identificable (PII) de tus usuarios, como sus IDs de Usuario, debes evaluar la solicitud a la luz de tus obligaciones legales. Más información se puede encontrar en RTBF y Creadores. Puedes crear un bot para manejar notificaciones de webhook y ayudar a automatizar la eliminación de datos, siempre que estés almacenando PII en un almacén de datos. Consulta Automatizando la Eliminación de Solicitudes de Derecho a la Eliminación para un ejemplo de cómo crear un bot dentro de Discord que utiliza la API de Nube Abierta para almacenes de datos para eliminar datos PII como una solución de automatización. Este ejemplo se puede adaptar 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 = '<tu_secreto>' // Esto puede establecerse 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);

   // Asegúrate de que la solicitud llegó 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 útil: UserId=${userId} y GameIds=${gameIds}`);
      // Si almacenas PII en almacenes de datos, usa el UserId y 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');
});