Notificações de webhook

Em vez de monitorar manualmente todos os eventos em sua experiência e solicitações de usuários, você pode configurar webhooks para receber notificações em tempo real em uma ferramenta de mensageria de terceiros ou em seu ponto final personalizado que possa receber solicitações HTTP.Isso ajuda você a automatizar seu fluxo de trabalho de gerenciamento de notificações para reduzir as notificações de esforço manual.

Atualmente, o Roblox suporta totalmente notificações de webhook para Discord, Guilded e Slack.Usar webhooks com outras ferramentas de terceiros carrega o risco de não receber todas as notificações.

Fluxo de trabalho de Webhook

Webhooks enviam notificações ou dados em tempo real entre dois aplicativos ou serviços diferentes, como Roblox e uma ferramenta de mensageria de terceiros.Ao contrário de APIs tradicionais, que exigem que você configure uma aplicação cliente para enviar solicitações a um servidor para receber dados, webhooks enviam dados para o ponto final do seu cliente assim que um evento ocorre.Eles são úteis para automatizar fluxos de trabalho entre o Roblox e aplicações de terceiros que você usa para colaborar com sua Equipe, pois permitem compartilhar e processar dados em tempo real.

Uma vez que você configura um webhook, sempre que um evento alvo ocorre, o Roblox envia um pedido para o URL do webhook que você fornecer / proporcionar.A URL do webhook então redireciona a solicitação para a sua aplicação de recebimento ou ponto final personalizado, que pode tomar medidas com base nos dados incluídos no payload do webhook.Isso pode incluir apagar dados para o Regulamento Geral sobre a Proteção de Dados, enviar uma confirmação ao usuário ou acionar outro evento.

Gatilhos suportados

O Roblox atualmente suporta os seguintes gatilhos de evento para notificações:

Subscrição cancelada - Quando um usuário cancela uma subscrição, uma mensagem é enviada contendo a subscrição e o subscritor, bem como a razão dada para o cancelamento.
Subscrição Comprada - Quando um usuário compra uma subscrição, uma mensagem é enviada contendo a subscrição e o subscritor.
Subscrição Reembolsada - Quando um usuário recebe um reembolso pela assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
Subscrição Renovada - Quando um usuário renova uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
Subscrição Resubscrita - Quando um usuário resubscreve a uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
"Direito de ser esquecido" pedidos de exclusão de dados sob o Regulamento Geral de Proteção de Dados ( GDPR ).

Para mais informações sobre eventos de subscrição e seus campos, veja a referência Subscrição da API da Nuvem.

Configurar webhooks no Painel do Criador

Para receber notificações através de webhooks, você precisa configurar um webhook que se subscribe a determinados eventos para disparar notificações.Para experiências de propriedade do grupo, apenas os proprietários de grupo podem configurar e receber notificações de webhook.

Se você estiver configurando webhooks e lidando com dados pessoais, garanta que eles estejam em conformidade com o Regulamento Geral de Proteção de Dados (Regulamento Geral sobre a Proteção de Dados).

Para configurar um webhook:

Navegue até a seção Webhooks do Painel do Criador.
Clique no botão Adicionar Webhook .
Complete os campos de configuração:
1. URL de webhook — Especifique o URL onde você deseja receber notificações e aceitar URLs de webhook de entidades de terceiros.Para mais informações sobre os requisitos, veja Configurar URLs de webhook.
2. Nome — Use um nome personalizado para diferenciar sua configuração de outras. Por padrão, o valor é o mesmo que o URL do Webhook.
3. Secreto (opcional) — Forneça um segredo se você quiser verificar se as notificações que recebe vêm do Roblox.Para mais informações, veja Verifique a segurança do webhook.
4. Gatilhos — Escolha uma ou mais opções da lista de gatilhos suportados de eventos para os quais você deseja receber notificações.
Clique no botão Salvar Alterações .

Atualmente, você pode configurar até 5 webhooks no total.

Configurar URLs de webhook

Você pode configurar um ponto de extremidade de serviço HTTP personalizado como seu URL de webhook, desde que ele atenda aos seguintes requisitos:

Deve ser acessível publicamente para lidar com solicitações.
Ele pode lidar com solicitações POST.
Ele pode responder à solicitação com uma resposta de 2XX dentro de 5 segundos.
Ele pode lidar com solicitações HTTPS.

Quando o seu endpoint recebe uma solicitar / pedirPOST, deve ser capaz de:

Extraia os detalhes necessários sobre a notificação do corpo da mensagem POST.
Leia o corpo da mensagem POST com os detalhes genéricos sobre a notificação e detalhes específicos relacionados ao tipo de evento na notificações.

Para mais informações sobre o esquema de solicitações POST para Manipulador / alça, veja o Esquema de Carga.

política de privacidadede revisão de falha de entrega

Quando uma notificação de webhook falha em alcançar o URL especificado devido a erros como indisponibilidade de endpoint, o Roblox tenta novamente enviar a mensagem para o URL configurado 5 vezes usando um tamanho de janela fixo.Se a notificação ainda não for entregue após 5 tentativas, o Roblox para de tentar enviar a notificação e supõe que o URL não é mais válido.Nesta situação, você precisa atualizar a configuração do webhook com uma nova URL que seja alcançável e capaz de receber notificações.Para solucionar problemas e confirmar que o URL do webhook pode receber notificações com sucesso, veja Testar webhooks.

Requisitos de terceiros

Ferramentas de terceiros geralmente têm seus próprios requisitos para webhooks que você precisa seguir ao configurar seu URL de webhook.Você pode encontrar esses requisitos pesquisando a palavra-chave "webhook" no site de suporte ou de documentação da ferramenta alvo.Para as três ferramentas de terceiros suportadas, veja o seguindo:

Testar webhooks

Você pode testar se o webhook que configurou pode receber notificações com sucesso no Painel do Criador:

Navegue até a página de configuração de Webhooks.
Selecione o webhook que você deseja testar da lista de webinks configurados.
Clique no ícone de lápis ao lado do webhook alvo.
Clique no botão Resposta de Teste .

O sistema então envia uma notificação no digitarSampleNotification, que inclui o ID do usuário do usuário que ativa a notificações, como mostra o seguinte esquema de exemplo:

Esquema de Notificação de Amostra
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Tipo: ISO 8601 Timestamp
  "EventPayload": {
    "UserId": 1 // Tipo: Longo
  }
}

Se você estiver integrando seu webhook com um serviço de terceiros, você pode testá-lo usando o URL de terceiros para confirmar que o serviço pode receber notificações com sucesso do seu webhook.Se você fornecer um segredo ao configurar o webhook, também gera um roblox-signature que você pode usar para testar a lógica roblox-signature.

Verifique a segurança do webhook

Uma vez que você configura seu servidor para receber cargas úteis, ele começa a ouvir qualquer carga enviada para o endpoint.Se você definir um segredo ao configurar seu webhook, o Roblox envia um roblox-signature junto com cada notificação de webhook para ajudar a proteger a segurança de seus dados.Dessa forma, você pode usar o it para verificar que a notificação é do Roblox e limitar seu servidor a receber apenas solicitações originadas do Roblox.A assinatura está no cabeçalho de pagamento para pontos finais personalizados e no rodapé para servidores de terceiros.

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

Se você não tiver um segredo para o seu webhook, a assinatura que você recebe só contém o valor do timestamp quando a notificação é enviada:

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

Para verificar uma assinatura:

Extraia os valores de data e assinatura.Todas as assinaturas para webhooks com segredos compartilham o mesmo formato de uma string CSV com esses dois valores seguidos pelos prefixos:
- t : O valor do horário de envio da notificação quando ela é sentença / frase
- v1 : O valor de assinatura gerado usando o segredo fornecido pela configuração do Painel do Criador.Você pode extrair esses dois valores usando a função split(), que separa a string com base em um separador, neste caso, o personagem ,.
Recrie a string base de roblox-signature concatenando:
1. O timestamp como uma string / cadeia / texto.
2. O personagem de período ..
3. A string JSON do corpo da solicitação.
Calcular um código de autenticação de mensagem baseado em hash (HMAC) com a função de hash SHA256 usando o segredo que você definiu durante a configuração como chave e a string base que você gerou através do passo 2 como mensagem.Converta o resultado para o formato Base64 para obter a assinatura esperada.
Compare o valor da assinatura extraída ao valor da assinatura esperada. Se você gerou a assinatura corretamente, o valor deve ser o mesmo.
(Opcional) Para evitar ataques de replay, um tipo de ataque cibernético onde os atacantes interceptam e reenviam dados para obter acesso não autorizado ou executar ações maliciosas, é útil comparar o valor do tempo de extracção com o tempo atual e garantir que ele caiba dentro de um limite de tempo razoável.Por exemplo, uma janela de 10 minutos é geralmente um bom limite de tempo razoável.

Esquema de pagamento

Quando o evento alvo do seu webhook é acionado, ele envia um pedido para o URL do seu webhook, incluindo informações sobre o evento no payload.Todos os payloads de solicitações compartilham o mesmo esquema que consiste em campos fixos e variáveis.Isso garante que os dados transmitidos no payload sejam estruturados e consistentes, tornando mais fácil para o aplicativo receptor processar e usar os dados.

Os campos de esquema de carga fixa pode ajudar a manter a consistência em todas as solicitações de webhook , com os seguintes campos disponíveis:

NotificationId , string : Um identificador exclusivo para cada notificação enviada. Se o mesmo NotificationId for recebido duas vezes, ele é considerado um duplicado.
EventType , string : Uma string representa o tipo de evento para o qual a notificação foi acionada.
EventTime , timestamp : Um timestamp aproximado indicando quando o evento foi acionado.

Os campos de esquema de carga variável fornecem flexibilidade para webhooks para acomodar vários tipos de eventos, que incluem:

EventPayload , object : Contém informações específicas para o EventType que disparou o webhook.A estrutura do esquema EventPayload variará dependendo do tipo de evento.

O seguinte exemplo mostra o esquema de payload do evento Direito à Solicitação de Apagamento :

Exemplo de esquema para solicitação de direito de apagamento
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

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

   "EventPayload": {

      "UserId": 1, // Tipo: Longo

      "GameIds": [ // Tipo: Um array de Longs

         1234, 2345

      ]

   }

}

Lidar com notificações

Se você armazenar qualquer Informação Pessoalmente Identificável (IIP) de seus usuários, como seus IDs de Usuário, você deve excluir essas informações quando um usuário enviar tal solicitação para cumprir os requisitos de conformidade do RGPD direito ao apagamento.Você pode criar um bot para lidar com notificações de webhook e ajudar a automatizar a exclusão de dados, desde que esteja armazenando PII em um armazenamento de dados.Veja Automatizando a Exclusão de Pedidos de Direito de Apagar para um exemplo de como criar um bot dentro do Guilded ou do Discord que use a API de Nuvem Aberta para armazenamento de dados para excluir dados PII como uma solução de automação.Este exemplo pode ser adaptado para lidar com outras notificações, como eventos de assinatura.

Se você usar um ponto de extremidade personalizado como seu servidor de webhook em vez de uma ferramenta de terceiros, você pode extrair os dados sujeitos à exclusão do payload de webhook e construir sua própria solução de automação.O seguinte exemplo de código fornece uma solução de exemplo e adiciona prevenção a ataques de replay verificando que a solicitação está vindo do 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')
})

Nesta página