Notificaciones de Webhook

*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.

En lugar de monitorear manualmente todos los eventos en su experiencia y solicitudes de los usuarios, puede configurar webhook para recibir notificaciones en tiempo real en una herramienta de mensajería en línea de terceros o en su punto de interfaz personalizado que puede recibir solicitudes HTTP. Esto ayuda a automatizar su flujo de trabajo de notificación para reducir el esfuerzo de trabajo manual.

flujo de trabajo de Webhook

Las llamadas webhook 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, las llamadas webhook envían datos a tu punto de interfaz de cliente tan pronto como ocurre un evento. Son útil

Una vez que configures un webhook, siempre que ocurra un evento de objetivo, Roblox envía una solicitud a la URL del webhook que proporcionar. La URL del webhook luego redirige la solicitud a tu aplicación de destino o punto de fin personalizado, lo que puede tomar acción en función de los datos incluidos en el webhook. Esto podría incluir eliminar datos para el cumplimiento de la RGDP, enviar una confirmación al usuario o activar otro evento.

Tradores admitidos

Roblox actualmente soporta los siguientes eventos para notificaciones:

  • Subscription Cancelled - Cuando un usuario puede cancelar una suscripción , se envía un mensaje que contiene el suscripción y el suscriptor, así como la razón dada para la cancelación.
  • Subscription Purchased - Cuando un usuario compra 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 Renovada - Cuando un usuario renueva una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
  • Suscripción Reabierta - Cuando un usuario reabre una suscripción, se envía un mensaje que contiene la suscripción y el suscriptor.
  • "Derecho a ser olvidado" solicitudes de eliminación de datos según el Reglamento General de Protección de Datos ( GDPR ).

Para obtener más información sobre los eventos de suscripción y sus campos, consulte la referencia Cloud API Subscription.

Configurando WebHooks en el Panel del Creador

Para recibir notificaciones a través de webHook, debe configurar un webHook que se suscriba a ciertos eventos para activar las notificaciones de trigger. Para las experiencias de propiedad del grupo, solo los propietarios del grupo pueden configurar y recibir notificaciones de webHook.

Para configurar un webhook:

  1. Navegue a la sección WebHooks de la Dashboard del Creador.
  2. Haga clic en el botón Añadir Webhook .
  3. Completa los campos de configuración:
    1. URL de Webhook — Especifique la URL donde desea recibir notificaciones y aceptar las URL de Webhook entrantes de terceras entidades. Para obtener más información sobre los requisitos, consulte Configurando Webhook URLs .
    2. Nombre — Usa un nombre personalizado para diferenciar tu configuración de la de otros. Por defecto, el valor es el mismo que el URL del enlace de Webhook.
    3. Secreto (opcional) — Proporcione un secreto si desea verificar que las notificaciones que recibe son de Roblox. Para obtener más información, consulte Verificando la seguridad del enlace web.
    4. Gatillos — Elige uno o más opciones de la lista de gatillos soportados de los eventos para los que quieres recibir notificaciones.
  4. Haga clic en el botón Guardar cambios .

Configurando URL de Webhook

Puede configurar un servicio de API HTTP personalizado como su URL de webhook, siempre que cumpla con los siguientes requisitos:

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

Cuando su punto de interfaz recibe una solicitud POST, debe ser capaz de:

  • Extrae los detalles requeridos acerca de la notificación del cuerpo del mensaje POST.
  • Lee 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 en la notificaciones.

Para obtener más información sobre el esquema de las solicitudes POST para controlador, see el Esquema de carga de trabajo .

Política de reutilización de los fallos de entrega

Cuando una notificación de webhook no llega a su URL especificada debido a errores como la disponibilidad del punto de extremo, Roblox reintenta enviar el mensaje a la URL configurada 5 veces usando un tamaño de ventana fijo. Si la notificación todavía no se envía después de 5 intentos, Roblox deja de intentar enviar la notificación y

Requisitos de terceros

Las herramientas de terceros generalmente tienen sus propias exigencias para los webhook que necesitas seguir al configurar la URL de tu webhook. Puedes encontrar estas exigencias buscando la palabra clave "webhook" en el sitio de soporte o documentación del herramienta objetivo. Para las tres herramientas de terceros admitidas, véase lo siguiendo:

Prueba de WebHooks

Puedes probar si el webhook que has configurado puede recibir notificaciones con éxito en la Crear pestaña de controlador :

  1. Navegue a la página de configuración de WebHooks.

  2. Seleccione el webhook que desea probar de la lista de webhook configuradas.

  3. Haga clic en el icono de lápiz junto con el enlace de destino.

    The pencil icon next to an example webhook

  4. Haga clic en el botón Respuesta de prueba .

El sistema luego envía una notificación en el introducirSampleNotification, que incluye el ID del usuario del usuario que activa la notificaciones, como se muestra en el siguiente esquema de ejemplo:

Esquema de notificación de muestras
Body: {

  "NotificationId": "string",

  "EventType": "SampleNotification",

  "EventTime": "2023-12-30T16:24:24.2118874Z", // Tipo: ISO 8601 Tempora de marcado

  "EventPayload": {

    "UserId": 1 // Tipo: Largo

  }

}

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 notificaciones con éxito de tu webhook. Si proporcionas una contraseña al configurar el webhook, también se genera un roblox-signature que puedes usar para probar la lógica del webhook.

Verificando la seguridad del Webhook

Una vez que configure su servidor para recibir cargas de trabajo, comienza a escuchar cualquier carga de trabajo enviada al punto de extremo. Si configura un secreto al configurar su webhook, Roblox envía una roblox-signature junto con cada notificación de webhook para ayudar a proteger la seguridad de sus datos. De esta manera, puede usar el it para

Signature Format with Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

Si no tienes un secreto para tu webhook, la firma que recibes solo contiene el valor de tiempo de envío en el momento en que se envía la notificación:

Signature Format without Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>"

Para verificar una firma:

  1. Extrae los valores de tiempo de marcado y firma. Todas las firmas para las llamadas web con secretos comparten el mismo formato que una cadena CSV con estos dos valores después de los sufijos:

    • t : El valor de tiempo de envío de la notificación.
    • v1 : El valor de firma generado utilizando la firma proporcionada por la configuración del panel de control del creador. Puedes extraer estos dos valores utilizando la función split(), que separa la cadena basada en un delimitador, en este caso, el personaje , .

  2. Re-crear la cadena de base de roblox-signature al concatenar:

    1. El tiempo de UTC como una cadena.
    2. El personaje de período . .
    3. La cadena JSON del cuerpo de la solicitud.

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

  4. Compare el valor de la firma extraído con el valor esperado. Si generaste la firma correctamente, el valor debería ser el mismo.

  5. (Opcional) Para evitar los ataques de repetición, un tipo de ataque cibernético en el que los atacantes interceptan y reenvían los datos para obtener un acceso no autorizado o realizar acciones maliciosas, es útil comparar el valor de tiempo de extracción con el tiempo de tiempo real actual y asegurarse de que caiga dentro de un límite de tiempo razonable. Por ejemplo, una ventana de 10 minutos es generalmente un buen límite de tiempo razonable.

Esquema de pago

Cuando se activa el evento objetivo de tu webhook, envía una solicitud a la URL de tu webhook, incluida la información sobre el evento en el cargador. Todos los cargadores de solicitudes comparten el mismo esquema que consiste en campos fijos y variables. Esto garantiza que los datos transmitidos en el cargador se estructuren y sean consistentes, lo que facilita que el aplicativo de destino procese y use los datos.

Los campos de esquema de carga de valor fijo pueden ayudar a mantener la consistencia en todos los solicitantes 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 duplicado.
  2. EventType , string : Una cadena representa el tipo de evento para el cual se activó la notificación.
  3. EventTime , timestamp : Fecha de tiempo aproximada que indica cuando se ha activado el evento.

Los campos de esquema de carga de 变 proporcionan flexibilidad para que los webhook puedan albergar varios tipos de eventos, que incluyen:

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

El siguiente ejemplo muestra el esquema de carga del derecho a solicitar el borrado evento:

Ejemplo de esquema para solicitud de derecho a eliminar
Body:{



   "NotificationId": "string",



   "EventType": "RightToErasureRequest",



   "EventTime": "2023-12-30T16:24:24.2118874Z",



   "EventPayload": {



      "UserId": 1, // Tipo: Largo



      "GameIds": [ // Tipo: Un matriz de Longs



         1234, 2345



      ]



   }



}

Manipulación de Notificaciones

Si almacena cualquier Información Personalmente Identificable (Información de Identificación Personal (IIP)) de sus usuarios, como sus ID de usuario, debe eliminar esta información cuando un usuario envíe una

Si usa un punto de extremo personalizado como su servidor de webhook en lugar de una herramienta de terceros, puede extraer los datos sujetos a la eliminación del punto de extremo y construir su propia solución de automatización. El siguiente código de ejemplo proporciona una solución de ejemplo y agrega la prevención de reprobar los ataques al verificar que la solicitud viene de Roblox:

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

const express = require('express');

let app = express();

app.use(express.json());

app.use(express.urlencoded({ extended: true }));

// This is a sample only code

app.all('/*', function (req, res) {

   console.log('-------- New Request Seen -------');

   // 1. Extract the timestamp and signature

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

   const hmac = crypto.createHmac('sha256', shared_secret)

   const roblox_signature_header = req.headers['roblox-signature'].split(',')

   // 'roblox-signature' is present in all requests:

   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.

   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='

   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);

   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));

   // 2. Prevent Replay attack: 300 seconds window

   const request_timestamp_ms = timestamp * 1000;

   const window_time_ms = 300 * 1000

   const oldest_timestamp_allowed = Date.now() - window_time_ms;

   if (request_timestamp_ms < oldest_timestamp_allowed) {

      res.status(403).send('Expired Request')

   }

   // 3. Validate Signature

   if (extracted_signature !== undefined) {

      const signature_v1 = extracted_signature.substring(3);

      const message = `${timestamp}.${JSON.stringify(req.body)}`

      const base64_signature = hmac.update(message).digest('base64')

      if (signature_v1 !== base64_signature) {

         res.status(401).send('Unauthorized Request')

      }

   }

   // 4. 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']

      const gameIdString = gameIds.toString()

      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)

      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.

   }

   // 5. Return Response

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

})

app.listen(8080, function () {

   console.log('This is a Sample application')

})