Notificações de Webhook

Em vez de monitorar manualmente todos os eventos em seu jogo e as solicitações 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 solicitações HTTP. Isso ajuda a automatizar seu fluxo de trabalho de gerenciamento de notificações para reduzir o esforço manual no manuseio 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 um aplicativo cliente para enviar solicitações a um servidor para receber dados, os webhooks enviam dados para 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 o compartilhamento e processamento de dados em tempo real.

Uma vez que você configure um webhook, sempre que um evento alvo ocorrer, o Roblox envia uma solicitação para a URL do webhook que você fornecer. A URL do webhook então redireciona a solicitação para sua aplicação receptora ou endpoint personalizado, que pode tomar ações 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 acionar outro evento.

Gatilhos suportados

Atualmente, o Roblox suporta os seguintes gatilhos de eventos.

Assinatura

• Assinatura Reassociada - Quando um usuário reassocia 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, bem como o motivo dado para o cancelamento.

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

Conformidade

• Direito ao Apagamento / Solicitação 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 Comercial Reembolsado - Quando um usuário recebeu um reembolso por seu pedido de produto comercial, ou o pedido foi cancelado.
• Pedido de Produto Comercial Pago - Quando um usuário pagou por seu pedido de produto comercial. Observe que eventos de webhook duplicados são possíveis, portanto, você deve deduplicar eventos usando o ID de pedido comercial exclusivo.

Configurar webhooks no Painel do Criador

Para receber notificações através de webhooks, você precisa configurar um webhook que se inscreva em certos eventos para acionar notificações. Para jogos de propriedade de grupos, apenas os proprietários do grupo podem configurar e receber notificações de webhook.

Para configurar um webhook:

1. Selecione sua experiência no Creator Hub.

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 isto:

   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 do 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 solicitação de exemplo.

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 lidar com solicitações.
• Pode lidar com solicitações POST.
• Pode responder à solicitação com uma resposta 2XX dentro de 5 segundos.
• Pode lidar com solicitações HTTPS.

Quando seu endpoint recebe uma solicitaçã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 solicitações POST a serem tratadas, consulte o Esquema da Carga Útil.

Política de retry em caso de falha de entrega

Quando uma notificação de webhook falha ao alcançar sua URL especificada devido a erros como indisponibilidade do endpoint, o Roblox tenta enviar a mensagem para a URL configurada 5 vezes usando um tamanho de janela fixo. Se a notificação ainda falhar em ser entregue após 5 tentativas, o 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 pela palavra-chave "webhook" no site de suporte ou documentação da ferramenta alvo. Para as ferramentas de terceiros suportadas, consulte 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 acionou a notificação, como mostrado aqui:

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

Se você estiver 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, o Roblox envia uma roblox-signature em cada notificação de webhook para garantir que a solicitação realmente veio do 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 contém apenas 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 solicitaçã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 a chave e a string base que você gerou na etapa 2 como a mensagem. Converta o resultado para o formato Base64 para obter a assinatura esperada.

4. Compare o valor da assinatura extraído 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 onde 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 é acionado, ele envia uma solicitação para sua URL de webhook, incluindo informações sobre o evento na carga útil. Todas as cargas úteis das solicitaçõ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 o processamento e uso dos dados pela aplicação receptora.

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

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

Os campos do esquema de carga útil variáveis fornecem flexibilidade para que os webhooks acomodem vários tipos de eventos, que incluem:

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

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

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

Lidar com 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 solicitação à luz de suas obrigações legais. Mais informações podem ser encontradas em RTBF e Criadores. Você pode criar um bot para lidar com notificações de webhook e ajudar a automatizar a exclusão de dados, desde que você esteja armazenando PII em um armazenamento de dados. Consulte Automatizando a Exclusão de Solicitações de Direito ao Apagamento para um exemplo de como criar um bot dentro do Discord que usa a API Open Cloud para armazenamentos 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 verificando o timestamp e que a solicitação está vindo do 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 solicitaçã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 solicitação veio 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('Solicitaçã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('Solicitação Não Autorizada');
   }

   // Sua lógica para lidar com 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 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');
});