Notificaciones de webhook

En lugar de monitorear manualmente todos los eventos de 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 webhooks

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 cliente tan pronto como ocurre un evento. Son útiles para automatizar flujos de trabajo entre Roblox y las 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 redirige la solicitud a tu aplicación receptora o punto final personalizado, que puede actuar basado en los datos incluidos en la carga útil del webhook. Esto podría incluir borrar datos por GDPR, enviar una confirmación al usuario o activar otro evento.

Disparadores compatibles

Roblox admite actualmente 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 al suscriptor.
• Suscripción Renovada - Cuando un usuario renueva una suscripción, se envía un mensaje que contiene la suscripción y al 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 al suscriptor.
• Suscripción Comprada - Cuando un usuario compra una suscripción, se envía un mensaje que contiene la suscripción y al suscriptor.
• Suscripción Cancelada - Cuando un usuario cancela una suscripción, se envía un mensaje que contiene la suscripción y al suscriptor, así como la razón dada para la cancelación.

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

Cumplimiento

• Solicitud de Derecho a la Supresión - Cuando un usuario envía una solicitud de eliminación de datos bajo el Reglamento General de Protección de Datos (GDPR).

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 su pedido de producto de comercio. Ten en cuenta que pueden ocurrir eventos de webhook duplicados, por lo que deberías deduplicar los eventos utilizando el ID de pedido de comercio único.

Configurar webhooks en Creator Dashboard

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 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 Añadir 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 asegurar que las notificaciones que recibes provengan 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 compatibles de eventos para los que deseas recibir notificaciones.

6. (Opcional) Usa el botón Respuesta de Prueba para comprobar 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 sobre la notificación.

Para más información sobre el esquema de solicitudes POST que 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 usando un tamaño de ventana fijo. Si la notificación sigue sin poder entregarse 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 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 suelen tener sus propios requisitos para webhooks que necesitas 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 de destino. Para las herramientas de terceros compatibles, 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 Creator Dashboard:

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 al lado del webhook objetivo.
4. Haz clic en el botón 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í:

Esquema de SampleNotification
{
  "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 utilizar para probar la lógica de roblox-signature.

Verificar la seguridad del webhook

Después de que configuras 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 asegurar 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.

Formato de la firma con un secreto para puntos finales personalizados
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:

Formato de la firma sin un secreto para puntos finales personalizados
t=<timestamp>

Para verificar una firma:

1. Extrae los valores de la marca de tiempo y la 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 Creator Dashboard.

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. Computa un código de autenticación de mensaje basado en hash (HMAC) con la función de 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 correctamente la firma, 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, 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 coherentes, lo que facilita a la aplicación receptora procesar y utilizar los datos.

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

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

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

1. EventPayload (objeto): Contiene información específica del EventType que activó el webhook. La estructura del esquema 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 Supresión:

Esquema de ejemplo para una Solicitud de Derecho a la Supresión
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Manejar notificaciones

Si almacenas alguna Información Personal Identificable (PII) de tus usuarios, como sus ID de Usuario, debes eliminar esta información cuando un usuario envíe tal solicitud para cumplir con los requisitos de cumplimiento de eliminación del GDPR derecho a la supresión. Puedes crear un bot para manejar las 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 Automatización de Solicitudes de Derecho a la Supresión para un ejemplo de 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 se puede adaptar para manejar otras notificaciones, como los eventos de suscripción.

Si usas 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 provenga de Roblox:

Extracción de PII de la Carga Útil
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);

   // Asegurarse 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 la 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 el GameIds para eliminar la información de la base de datos.
   }

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

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