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 RGDP, enviar una confirmación al usuario o activar otro evento.
Gatillos admitidos
Roblox actualmente soporta los siguientes gatillos de evento para notificaciones:
- 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.
- 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 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 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.
- "Derecho a ser olvidado" solicitudes de eliminación de datos bajo el Reglamento General de Protección de Datos ( GDPR ).
Para obtener más información sobre eventos de suscripción y sus campos, consulte la referencia Suscripción de API de nube.
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 (RGDP).
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:
- URL del punto final web — Especifique la URL donde desea recibir notificaciones y aceptar URL de punto final web de entidades de terceros.Para obtener más información sobre los requisitos, consulte Configurar URL de webhook.
- Nombre — Utilice un nombre personalizado para diferenciar su configuración de otras. Por defecto, el valor es el mismo que la URL de Webhook.
- 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.
- 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 notificaciones.
Para obtener más información sobre el esquema de solicitudes POST para controlador, consulte el esquema de carga.
política de privacidadde 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 siguiendo:
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 una notificación en el introducirSampleNotification, que incluye el ID de usuario del usuario que activa la notificaciones, como muestra el siguiente esquema de ejemplo:
Esquema de notificación de muestra
Body: {
"NotificationId": "string",
"EventType": "SampleNotification",
"EventTime": "2023-12-30T16:24:24.2118874Z", // Tipo: ISO 8601 Timestamp
"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 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
Una vez que configures tu servidor para recibir cargas útiles, empieza a escuchar cualquier pago enviado al punto final.Si configuras un secreto al configurar tu webhook, Roblox envía un roblox-signature junto con cada notificación de webhook para ayudar a proteger la seguridad de tus datos.De esta manera, puedes usar el para verificar que la notificación provenga de Roblox y limitar tu servidor a recibir solicitudes que provengan solo 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 Secret for Custom Endpoints
Si no tienes un secreto para tu webhook, la firma que recibes solo contiene el valor del tiempo de envío de la notificación:
Signature Format without Secret for Custom Endpoints
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 : El valor de la hora de envío de la notificación cuando se adpo
- v1 : El valor de firma generado utilizando el secreto proporcionado por la configuración del tablero de mando del Creador.Puedes extraer estos dos valores usando la función split(), que separa la cadena según un delimitador, en este caso, el personaje ,.
Re-crea la cadena base de roblox-signature concatenando:
- La fecha y hora como cadena.
- El carácter de período ..
- La cadena JSON del cuerpo de la solicitud.
Calcular un código de autenticación de mensaje 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 , string : Un identificador único para cada notificación enviada. Si se recibe el mismo NotificationId dos veces, se considera duplicado.
- EventType , string : Una cadena representa el tipo de evento para el cual se activó la notificación.
- EventTime , timestamp : Una fecha aproximada que indica cuándo 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 , object : Contiene información específica para el 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 del evento Derecho a solicitar la eliminación :
Ejemplo de esquema para solicitud de derecho de supresión
Body:{
"NotificationId": "string",
"EventType": "RightToErasureRequest",
"EventTime": "2023-12-30T16:24:24.2118874Z",
"EventPayload": {
"UserId": 1, // Tipo: Largo
"GameIds": [ // Tipo: Un array de Longs
1234, 2345
]
}
}
Manija de notificaciones
Si almacenas cualquier Información personalmente identificable (Información de Identificación Personal (IIP)) 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 tiendade 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 proporciona una solución de ejemplo y agrega prevención a los ataques de repetición verificando que la solicitud proviene 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')
})