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 mensagens de terceiros ou em seu ponto final personalizado que pode receber solicitações HTTP. Isso ajuda você a automatizar seu fluxo de gerenciamento de notificações, reduzindo o esforço manual no tratamento de notificações.

Fluxo de trabalho de 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 solicitações a um servidor para receber dados, os webhooks enviam dados para o seu ponto final 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.

Depois de configurar um webhook, sempre que um evento-alvo ocorrer, a 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 ponto final personalizado, que pode tomar uma ação com base nos dados incluídos na carga útil do webhook. Isso pode incluir apagar dados para conformidade com o GDPR, enviar uma confirmação para o usuário ou acionar outro evento.

Gatilhos suportados

A Roblox atualmente suporta os seguintes gatilhos de evento.

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, assim como a razão fornecida para o cancelamento.

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

Conformidade

• Solicitação de Direito de Apagar - Quando um usuário envia uma solicitação de exclusão de dados sob o Regulamento Geral sobre a Proteção de Dados (GDPR).

Comércio

• Pedido de Produto Comercial Reembolsado - Quando um usuário recebe 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. Por favor, note que eventos de webhook duplicados são possíveis, então você deve deduplicar eventos usando o ID de pedido de comércio único.

Configurar webhooks no Painel do Criador

Para receber notificações por meio de webhooks, você precisa configurar um webhook que se inscreve em certos eventos para acionar notificações. Para experiências 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 Criador 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 parece assim:

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

3. Insira sua URL do 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, veja Verificar segurança do webhook.

5. Escolha uma ou mais opções na 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 amostra.

7. Clique em Salvar Alterações.

Configurar URLs de webhook

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

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

Quando seu ponto final 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 da notificação e detalhes específicos relacionados ao tipo de evento da notificação.

Para mais informações sobre o esquema das solicitações POST a serem tratadas, veja o Esquema de Carga Útil.

Política de retry para falha de entrega

Quando uma notificação de webhook falha em alcançar sua URL especificada devido a erros como indisponibilidade do ponto final, a 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, 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 se sua URL de 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 sua URL de webhook. Você pode encontrar esses requisitos pesquisando pela palavra-chave "webhook" no site de suporte ou documentação do ferramenta alvo. 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 consegue 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, conforme mostrado aqui:

Esquema de SampleNotification
{
  "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, você pode testá-lo usando a URL de terceiros para confirmar que o serviço pode receber notificações do seu webhook com sucesso. 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 ouvir qualquer carga enviada ao ponto final. 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 solicitação realmente veio da Roblox. A assinatura está no cabeçalho da carga útil para pontos finais personalizados e no rodapé para servidores de terceiros.

Formato de Assinatura com um segredo para pontos finais personalizados
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:

Formato de Assinatura sem um segredo para pontos finais personalizados
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 precedidos por os prefixos:

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

2. Recreie a string base de 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 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.

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 os atacantes interceptam e reenviam dados para obter acesso não autorizado ou realizar ações maliciosas, é útil comparar o valor de timestamp extraído com o timestamp atual e garantir que ele caia dentro de um limite de tempo razoável. Por exemplo, um intervalo 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 fixos do esquema da carga útil 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 ú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 acionada.
3. EventTime (string): O timestamp de quando o evento foi acionado.

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

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

O seguinte exemplo mostra o esquema da carga útil para o evento de solicitação de Direito de Apagar:

Esquema de exemplo para uma solicitação de Direito de Apagar
{
   "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 excluir essa informação quando um usuário enviar tal solicitação para cumprir os requisitos de conformidade com o direito de apagar do GDPR. 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 Solicitações de Direito de Apagar para um exemplo de como criar um bot dentro do Discord que usa a API Open Cloud para armazenamento de dados para excluir dados de 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 final 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 se a solicitação está vindo da Roblox:

Extraindo PII da Carga Útil
const crypto = require('crypto');
const express = require('express');

const secret = '<seu_segredo>' // 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);

   // Garantir que a solicitação veio dentro de uma janela de 300 segundos para prevenir 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: 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');
});