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ê fornece.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 GDPR, enviar uma confirmação ao usuário ou acionar outro evento.

Gatilhos suportados

O Roblox atualmente suporta os seguintes gatilhos de evento.

Subscrição

Subscrição Resubscrita - Quando um usuário resubscreve a uma 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 Reembolsada - Quando um usuário recebe um reembolso pela assinatura, uma mensagem é enviada contendo a assinatura e o assinante.
Subscrição Comprada - Quando um usuário compra uma subscrição, uma mensagem é enviada contendo a subscrição e o subscritor.
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.

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

Conformidade

Direito de solicitação de exclusão de dados - Quando um usuário envia um pedido de exclusão de dados sob o Regulamento Geral de Proteção de Dados (GDPR).

Comércio

Ordem de produto comercial reembolsada - Quando um usuário recebeu um reembolso por sua ordem de produto comercial ou a ordem foi cancelada.
Pedido de Produto Comercial Pago - Quando um usuário pagou pelo pedido do produto comercial.Observe que eventos de webhook duplicados são possíveis, então você deve deduzir eventos usando o ID de 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 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 (GDPR).

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 do Webhook - Especifique o URL onde você deseja receber notificações.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 solicitação POST, 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ção.

Para mais informações sobre o esquema de solicitações POST para lidar, veja o Esquema de Carga.

Política de 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 seguinte:

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 um evento SampleNotification, que inclui o ID do usuário do usuário que disparou a notificação, como mostrado aqui:

Esquema de notificação de amostra
{
  "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 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

Depois de configurar 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 em cada notificação de webhook para garantir que a solicitação realmente veio do Roblox.A assinatura está no cabeçalho de pagamento para pontos finais personalizados e no rodapé para servidores de terceiros.

Signature format with a secret for custom endpoints
t=<timestamp>,v1=<signature>

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

Signature format without a secret for custom endpoints
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 horário de quando a notificação foi enviada.
- v1 : O valor de assinatura gerado usando o segredo fornecido pela configuração do Painel do Criador.
Recrie a string base de roblox-signature concatenando:
1. O timestamp como uma string.
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): Indica o tipo de evento para o qual a notificação foi acionada.
EventTime (string): O horário de 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 (objeto): Contém informações específicas para o EventType que disparou o webhook.A estrutura do esquema EventPayload varia dependendo do tipo de evento.

O seguinte exemplo mostra o esquema de payload da solicitação Direito de Apagar evento:

Esquema de exemplo para um pedido 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 Pessoalmente Identificável (PII) 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 é um exemplo de um servidor que tem prevenção contra ataques de replay verificando o timestamp e que a solicitação está vindo do Roblox:

Extracting PII from Payload
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // This can be set as an environment variable

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

app.all('/*', function (req, res) {
   console.log('New request recieved');

   // Extract the timestamp and signature from header
   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);

   // Ensure the request came within a 300 second window to prevent replay attacks
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Expired Request');
   }

   // Validate signature
   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('Unauthorized Request');
   }

   // 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'];

      console.log(`Payload data: UserId=${userId} and GameIds=${gameIds}`);
      // If you store PII in data stores, use the UserId and GameIds to delete the information from data stores.
   }

   return res.json({ message: 'Processed the message successfully' });
});

app.listen(8080, function () {
   console.log('Server started');
});

Nesta página