Notificaciones de webhook

En lugar de monitorear manualmente todos los eventos en tu experiencia y solicitudes de 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 le ayuda a automatizar su flujo de trabajo de gestión de notificaciones para reducir las notificaciones de esfuerzo manual.

Actualmente, Roblox admite completamente las notificaciones de webhook para Discord, Guilded y Slack.El uso de webhooks con otras herramientas de terceros conlleva el riesgo de no recibir todas las 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 de cliente tan pronto como ocurre un evento.Son útiles para automatizar flujos de trabajo entre Roblox y aplicaciones de terceros que usas 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 proporciones.La URL del webhook luego redirige la solicitud a tu aplicación receptora o punto final personalizado, que puede tomar acción en función de los datos incluidos en el pago de webhook.Esto podría incluir borrar datos para el GDPR, enviar una confirmación al usuario o activar otro evento.

Gatillos admitidos

Roblox actualmente soporta los siguientes gatillos de evento.

Suscripción

Suscripción reasignada - Cuando un usuario se vuelve a suscribir 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 obtener más información sobre eventos de suscripción y sus campos, consulte la referencia Suscripción.

Cumplimiento

Derecho a solicitar la supresión de datos - Cuando un usuario envía una solicitud de eliminación de datos bajo el Reglamento general de protección de datos (GDPR).

Comercio

Reembolso del pedido de producto comercial - Cuando un usuario ha recibido un reembolso por su pedido de producto comercial, o el pedido fue cancelado.
Orden de producto de comercio pagada - Cuando un usuario ha pagado por su orden de producto de comercio.Tenga en cuenta que los eventos de webhook duplicados son posibles, por lo que debe deducir eventos utilizando el ID de pedido de comercio único.

Configurar webhooks en el tablero de Creator

Para recibir notificaciones a través de webhooks, necesitas configurar un webhook que se suscriba a ciertos eventos para enviar notificaciones.Para las experiencias de propiedad del grupo, solo los propietarios del grupo pueden configurar y recibir notificaciones webhook.

Si estás configurando webhooks y manejando datos personales, asegúrate de que cumplan con el Reglamento general de protección de datos (GDPR).

Para configurar un webhook:

Navegue a la sección Webhooks del tablero de control del creador.
Haga clic en el botón Añadir Webhook .
Completa los campos de configuración:
1. URL del webhook - Especifique la URL donde desea recibir notificaciones.Para obtener más información sobre los requisitos, consulte Configurar URL de webhook.
2. Nombre - Usa un nombre personalizado para diferenciar tu configuración de otras. Por defecto, el valor es el mismo que la URL del Webhook.
3. Secreto (opcional) - Proporcione un secreto si desea verificar que las notificaciones que recibe provienen de Roblox.Para obtener más información, vea Verificar la seguridad del webhook.
4. Gatillos - Elige una o más opciones de la lista de gatillos admitidos de eventos para los que quieres recibir notificaciones.
Haga clic en el botón Guardar cambios .

Actualmente, puedes configurar hasta 5 webhooks en total.

Configurar URL 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 de 2XX dentro de 5 segundos.
Puede manejar solicitudes HTTPS.

Cuando tu punto final reciba una solicitud POST, debe poder:

Extrae los detalles requeridos sobre la notificación del cuerpo del mensaje POST.
Lee el cuerpo del mensaje POST con los detalles generales sobre la notificación y detalles específicos relacionados con el tipo de evento en la notificación.

Para obtener más información sobre el esquema de solicitudes POST para manejar, consulte el esquema de carga.

Política de reintento de fallo de entrega

Cuando una notificación de webhook no llega a la URL especificada debido a errores como la indisponibilidad del punto final, Roblox vuelve a enviar el mensaje a la URL configurada 5 veces usando 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 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, ve a Probar webhooks.

Requisitos de terceros

Las herramientas de terceros suelen tener sus propios requisitos para los webhooks que debe seguir al configurar su URL de webhook.Puedes encontrar estos requisitos buscando la palabra clave "webhook" en el sitio de soporte o documentación del herramienta objetivo.Para las tres herramientas de terceros admitidas, consulte lo siguiente:

Probar ganchos web

Puedes probar si el webhook que has configurado puede recibir con éxito notificaciones en el tablero de administrador del creador:

Navegue a la página de configuración de Webhooks.
Seleccione el webhook que desea probar de la lista de webhooks configurados.
Haga clic en el icono de lápiz junto al webhook objetivo.
Haga clic en el botón Respuesta de prueba .

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

Esquema de notificación de muestra
{
  "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 usando la URL de terceros para confirmar que el servicio puede recibir con éxito notificaciones de tu webhook.Si proporciona un secreto al configurar el webhook, también genera un roblox-signature que puede usar para probar la lógica roblox-signature.

Verificar la seguridad del punto final web

Después de configurar su servidor para recibir cargas útiles, comienza a escuchar cualquier pago enviado al punto final.Si configura un secreto al configurar su webhook, Roblox envía un roblox-signature en cada notificación de webhook para asegurarse de que la solicitud realmente provenga 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.

Signature format with a secret for custom endpoints
t=<timestamp>,v1=<signature>

Si no configuraste un secreto para tu webhook, la firma solo contiene la fecha y hora de envío de la notificación:

Signature format without a secret for custom endpoints
t=<timestamp>

Para verificar una firma:

Extrae los valores de tiempo y firma.Todas las firmas para webhooks con secretos comparten el mismo formato que una cadena CSV con estos dos valores seguidos por los prefijos:
- t : La fecha y hora de envío de la notificación.
- v1 : El valor de firma generado utilizando el secreto proporcionado por la configuración del tablero de mando del Creador.
Re-crea la cadena base de roblox-signature concatenando:
1. La fecha y hora como cadena.
2. El carácter de período ..
3. La cadena JSON del cuerpo de la solicitud.
Calcular un código de autenticación de mensajes basado en hash (HMAC) con la función de hash SHA256 usando el secreto que definiste durante la configuración como clave y la cadena base que generaste a través del paso 2 como mensaje.Convierte el resultado al formato Base64 para obtener la firma esperada.
Compare el valor de firma extraído con la firma esperada. Si generó la firma correctamente, el valor debería ser el mismo.
(Opcional) Para prevenir ataques de repetición, un tipo de ataque cibernético en el que los atacantes interceptan y reenvían datos para obtener acceso no autorizado o realizar acciones maliciosas, es útil comparar el valor del tiempo de extracción con el tiempo actual y asegurarse de que caiga dentro de un límite de tiempo razonable.Por ejemplo, una ventana de 10 minutos es usualmente un buen límite de tiempo razonable.

Esquema de carga

Cuando se activa el evento objetivo de tu webhook, envía una solicitud a la URL de tu webhook, que incluye información sobre el evento en el cuerpo de la solicitud.Todos los payloads de solicitudes comparten el mismo esquema que consiste en campos fijos y variables.Esto garantiza que los datos transmitidos en la carga útil estén estructurados y consistentes, lo que facilita que la aplicación receptora procese y use los datos.

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

NotificationId (texto): Un identificador único para cada notificación enviada. Si se recibe el mismo NotificationId dos veces, se considera duplicado.
EventType (texto): Indica el tipo de evento para el que se activó la notificación.
EventTime (texto): La marca de tiempo de cuando se activó el evento.

Los campos de esquema de carga de la variable proporcionan flexibilidad para que los webhooks puedan alojar varios tipos de eventos, que incluyen:

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 la carga útil de la solicitud Derecho a la eliminación del evento:

Ejemplo de esquema para una solicitud de derecho de supresión
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Manija de notificaciones

Si almacenas cualquier Información personalmente identificable (PII) de tus usuarios, como sus ID de usuario, debes eliminar esta información cuando un usuario envíe una solicitud para cumplir con los requisitos de cumplimiento del GDPR derecho de supresión.Puedes crear un bot para manejar notificaciones de webhook y ayudar a automatizar la eliminación de datos, siempre que almacenes PII en un almacén de datos.Vea Automatización de la eliminación de solicitudes de derecho de supresión para un ejemplo de cómo crear un bot dentro de Guilded o Discord que use la API de nube abierta para almacenamiento de datos para eliminar datos de PII como solución de automatización.Este ejemplo se puede adaptar para manejar otras notificaciones, como eventos de suscripción.

Si usa un punto final personalizado como servidor de webhook en lugar de una herramienta de terceros, puede extraer los datos sujetos a eliminación del pago de webhook y construir su 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 fecha y hora de la solicitud y que la solicitud proviene de Roblox:

Extracting PII from Payload
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // This can be set as an environment variable

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

app.all('/*', function (req, res) {
   console.log('New request recieved');

   // Extract the timestamp and signature from header
   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);

   // Ensure the request came within a 300 second window to prevent replay attacks
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

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

   // Validate signature
   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('Unauthorized Request');
   }

   // Your logic to handle payload
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Payload data: UserId=${userId} and GameIds=${gameIds}`);
      // If you store PII in data stores, use the UserId and GameIds to delete the information from data stores.
   }

   return res.json({ message: 'Processed the message successfully' });
});

app.listen(8080, function () {
   console.log('Server started');
});

En esta página