Notificações de webhook

Em vez de monitorar manualmente todos os eventos no seu jogo e os pedidos dos usuários, você pode configurar webhooks para receber notificações em tempo real em uma ferramenta de mensagens de terceiros ou em seu endpoint personalizado que pode receber requisições HTTP. Isso ajuda a automatizar seu fluxo de trabalho de gerenciamento de notificações para reduzir o esforço manual no tratamento de notificações.

Fluxo de trabalho do webhook

Webhooks enviam notificações ou dados em tempo real entre duas aplicações ou serviços diferentes, como Roblox e uma ferramenta de mensagens de terceiros. Ao contrário das APIs tradicionais, que exigem que você configure uma aplicação cliente para enviar requisições a um servidor para receber dados, os webhooks enviam dados para o seu endpoint cliente assim que um evento ocorre. Eles são úteis para automatizar fluxos de trabalho entre Roblox e aplicações de terceiros que você usa para colaborar com sua equipe, pois permitem compartilhamento e processamento de dados em tempo real.

Uma vez que você configura um webhook, sempre que um evento de destino ocorre, a Roblox envia uma requisição para a URL do webhook que você fornecer. A URL do webhook então redireciona a requisição para sua aplicação receptora ou endpoint personalizado, que pode tomar medidas com base nos dados incluídos na carga útil do webhook. Isso pode incluir apagar dados para conformidade com RTBF, enviar uma confirmação ao usuário ou disparar outro evento.

Gatilhos suportados

Atualmente, a Roblox suporta os seguintes gatilhos de eventos.

Assinatura

• Assinatura Reassociada - Quando um usuário reassocia a uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
• Assinatura Renovada - Quando um usuário renova uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
• Assinatura Reembolsada - Quando um usuário recebe um reembolso por sua assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
• Assinatura Comprada - Quando um usuário compra uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
• Assinatura Cancelada - Quando um usuário cancela uma assinatura, uma mensagem é enviada contendo a assinatura e o assinante, assim como a razão dada para o cancelamento.

Para mais informações sobre eventos de assinatura e seus campos, consulte a referência de Assinatura.

Conformidade

• Direito ao Apagamento / Pedido de Exclusão - Quando um usuário exerce seu direito de ter suas informações pessoais permanentemente excluídas sob as regulamentações globais de proteção de dados e privacidade aplicáveis. Mais informações podem ser encontradas em RTBF e Criadores.

Comércio

• Pedido de Produto de Comércio Reembolsado - Quando um usuário recebe um reembolso por seu pedido de produto de comércio, ou o pedido foi cancelado.
• Pedido de Produto de Comércio Pago - Quando um usuário pagou pelo seu pedido de produto de comércio. Observe que eventos de webhook duplicados são possíveis, portanto, você deve deduplicar eventos usando o ID do pedido de comércio exclusivo.

Configurar webhooks no Painel do Criador

Para receber notificações através de webhooks, você precisa configurar um webhook que assina certos eventos para disparar notificações. Para jogos de propriedade de grupos, apenas os donos do grupo podem configurar e receber notificações de webhook.

Para configurar um webhook:

1. Selecione sua experiência no Painel do Criador.

2. Em Configurar, selecione Webhooks e clique em Adicionar Webhook.

   A URL do webhook vem do seu provedor. Por exemplo, uma URL do Slack provavelmente se parece com isso:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Insira sua URL de webhook e um nome.

4. (Opcional) Inclua um segredo, que ajuda a garantir que as notificações que você recebe estão vindo da Roblox. Para mais informações, consulte Verificar segurança do webhook.

5. Escolha uma ou mais opções da lista de gatilhos suportados de eventos para os quais você deseja receber notificações.

6. (Opcional) Use o botão Testar Resposta para verificar se seu serviço pode receber uma requisição de amostra.

7. Clique em Salvar Alterações.

Configurar URLs de webhook

Você pode configurar um endpoint de serviço HTTP personalizado como sua URL de webhook, desde que atenda aos seguintes requisitos:

• Deve ser acessível publicamente para manipular requisições.
• Pode lidar com requisições POST.
• Pode responder à requisição com uma resposta 2XX dentro de 5 segundos.
• Pode lidar com requisições HTTPS.

Quando seu endpoint receber uma requisição POST, ele deve ser capaz de:

• Extrair os detalhes necessários sobre a notificação do corpo da mensagem POST.
• Ler 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ção.

Para mais informações sobre o esquema das requisições POST a serem manipuladas, consulte o Esquema da Carga Útil.

Política de repetição de falha de entrega

Quando uma notificação de webhook falha em chegar à sua URL especificada devido a erros como a indisponibilidade do endpoint, a Roblox tenta enviar a mensagem para a URL configurada 5 vezes usando um tamanho de janela fixo. Se a notificação continuar a falhar em ser entregue após 5 tentativas, a Roblox para de tentar enviar a notificação e assume que a URL não é mais válida. Nessa situação, você precisa atualizar sua configuração de webhook com uma nova URL que seja acessível e capaz de receber notificações. Para solucionar problemas e confirmar que sua URL de webhook pode receber notificações com sucesso, consulte Testar webhooks.

Requisitos de terceiros

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

• Central de Ajuda do Discord
• Referência da API do Slack

Testar webhooks

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

1. Navegue até a página de configuração de Webhooks.
2. Selecione o webhook que você deseja testar na lista de webhooks configurados.
3. Clique no ícone de lápis ao lado do webhook alvo.
4. Clique no botão Testar Resposta.

O sistema então envia um evento SampleNotification, que inclui o ID do Usuário do usuário que disparou a notificação, como mostrado aqui:

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

Se você está integrando seu webhook com um serviço de terceiros, pode testá-lo usando a 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, ele também gera uma roblox-signature que você pode usar para testar a lógica da roblox-signature.

Verificar segurança do webhook

Depois de configurar seu servidor para receber cargas úteis, ele começa a escutar por qualquer carga útil enviada para o endpoint. Se você definiu um segredo ao configurar seu webhook, a Roblox envia uma roblox-signature em cada notificação de webhook para garantir que a requisição realmente veio da Roblox. A assinatura está no cabeçalho da carga útil para endpoints personalizados e no rodapé para servidores de terceiros.

t=<timestamp>,v1=<signature>

Se você não definiu um segredo para seu webhook, a assinatura apenas contém o timestamp de quando a notificação foi enviada:

t=<timestamp>

Para verificar uma assinatura:

1. Extraia os valores de timestamp e assinatura. Todas as assinaturas para webhooks com segredos compartilham o mesmo formato como uma string CSV com esses dois valores seguidos pelos prefixos:

   • t: O timestamp de quando a notificação foi enviada.
   • v1: O valor da assinatura gerado usando o segredo fornecido pela configuração do Painel do Criador.

2. Recrie a string base da roblox-signature concatenando:

   1. O timestamp como uma string.
   2. O caractere de ponto ..
   3. A string JSON do corpo da requisição.

3. Calcule um código de autenticação de mensagem baseado em hash (HMAC) com a função hash SHA256 usando o segredo que você definiu durante a configuração como chave e a string base que você gerou na etapa 2 como mensagem. Converta o resultado para o formato Base64 para obter a assinatura esperada.

4. Compare o valor da assinatura extraída com a assinatura esperada. Se você gerou a assinatura corretamente, o valor deve ser o mesmo.

5. (Opcional) Para evitar ataques de repetição, um tipo de ataque cibernético em que atacantes interceptam e reenviam dados para obter acesso não autorizado ou realizar ações maliciosas, é útil comparar o valor do timestamp extraído com o timestamp atual e garantir que ele esteja dentro de um limite de tempo razoável. Por exemplo, uma janela de 10 minutos geralmente é um bom limite de tempo razoável.

Esquema da carga útil

Quando o evento alvo do seu webhook é disparado, ele envia uma requisição para sua URL de webhook, incluindo informações sobre o evento na carga útil. Todas as cargas úteis das requisições compartilham o mesmo esquema que consiste em campos fixos e variáveis. Isso garante que os dados transmitidos na carga útil sejam estruturados e consistentes, facilitando para a aplicação receptora processar e usar os dados.

Os campos do esquema de carga útil fixos podem ajudar a manter a consistência em todas as requisições de webhook, com os seguintes campos disponíveis:

1. NotificationId (string): Um identificador único para cada notificação enviada. Se o mesmo NotificationId for recebido duas vezes, ele é considerado um duplicado.
2. EventType (string): Indica o tipo de evento para o qual a notificação foi disparada.
3. EventTime (string): O timestamp de quando o evento foi disparado.

Os campos do esquema de carga útil variáveis oferecem flexibilidade para que os webhooks se adaptem a vários tipos de eventos, que incluem:

1. EventPayload (objeto): Contém informações específicas para o EventType que disparou o webhook. A estrutura do esquema do EventPayload varia com base no tipo de evento.

O seguinte exemplo mostra o esquema da carga útil do evento de Pedido de Direito ao Apagamento:

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Manipular notificações

Se você armazenar qualquer Informação Pessoal Identificável (PII) de seus usuários, como seus IDs de Usuário, você deve avaliar a requisição à luz de suas obrigações legais. Mais informações podem ser encontradas em RTBF e Criadores. Você pode criar um bot para manipular notificações de webhook e ajudar a automatizar a exclusão de dados, desde que esteja armazenando PII em um armazenamento de dados. Consulte Automatizando a Exclusão de Pedidos de Direito ao Apagamento para um exemplo de como criar um bot dentro do Discord que usa a API do Open Cloud 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 endpoint personalizado como seu servidor de webhook em vez de uma ferramenta de terceiros, pode extrair os dados sujeitos à exclusão da carga útil do webhook e construir sua própria solução de automação. O seguinte exemplo de código é um exemplo de um servidor que tem prevenção contra ataques de repetição ao verificar o timestamp e que a requisição está vindo da Roblox:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // Isso pode ser definido como uma variável de ambiente

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

app.all('/*', function (req, res) {
   console.log('Nova requisição recebida');

   // Extraia o timestamp e a assinatura do cabeçalho
   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);

   // Certifique-se de que a requisição ocorreu dentro de uma janela de 300 segundos para evitar ataques de repetição
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Requisição Expirada');
   }

   // Validar assinatura
   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('Requisição Não Autorizada');
   }

   // Sua lógica para manipular a 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(`Dados da carga útil: UserId=${userId} e GameIds=${gameIds}`);
      // Se você armazenar PII em armazenamentos de dados, use o UserId e os GameIds para excluir as informações dos armazenamentos de dados.
   }

   return res.json({ message: 'Mensagem processada com sucesso' });
});

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