Notificações de Webhook

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

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 de terminação personalizado que pode receber solicitações HTTP. Isso ajuda a automatizar sua gestão de notificações para reduzir o esforço de trabalho de notificação manual.

fluxo de trabalho de Webhook

Os WebHooks enviam notificações ou dados em tempo real entre duas aplicações ou serviços diferentes, como o Roblox e uma ferramenta de mensageria de terceiros. Ao contrário das APIs tradicionais, que exigem que você instale um cliente para enviar pedidos para um servidor para receber dados, os WebHooks enviam dados para o seu cliente端 como um momento que ocorre um evento. Eles são úteis

Um vez que você configura um webhook, sempre que um evento de alvo ocorre, o Roblox envia uma solicitação para a URL do webhook que você fornecer / proporcionar. A URL do webhook, em seguida, redireciona a solicitação para o endereço de destino que você forneceu, o que pode levar a ação com base nos dados incluídos no webhook. Isso pode incluir excluir dados para o Regulamento Geral sobre a Proteção de Dados, enviar uma confirmação ao usuário ou iniciar outro evento.

Gatilhos Suportados

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

  • Subscrição cancelada - Quando um usuário pode cancelar 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 sua subscrição, uma mensagem é enviada contendo a subscrição e o subscritor.
  • Subscrição Renovada - Quando um usuário renova uma subscrição, uma mensagem é enviada contendo a subscrição e o subscritor.
  • Subscription Resubscribed - Quando um usuário resubscrito para uma assinatura, uma mensagem é enviada contendo a assinatura e o subscritor.
  • "Direito de ser esquecido" solicitações de exclusão de dados sob o Regulamento Geral de Proteção de Dados ( GDPR ).

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

Configurando WebHooks no Painel do Criador

Para receber notificações por meio de webHooks, você precisa configurar um webHook que se inscreve em determinados eventos para disparar notificações. Para experiências de propriedade do grupo, apenas os proprietários do grupo podem configurar e receber notificações de webHook.

Para configurar um webhook:

  1. Navegue até a seção WebHooks da página Painel do Criador.
  2. Clique no botão Adicionar Webhook .
  3. Complete os campos de configuração:
    1. URL do Webhook — Especificar a URL onde você deseja receber notificações e aceitar URLs de webhook recebidos de terceiros. Para mais informações sobre os requisitos, veja Configurando URLs do Webhook.
    2. Nome — Use um nome personalizado para diferenciar sua configuração de outros. Por padrão, o valor é o mesmo que a URL do Webhook.
    3. Secreto (opcional) — Forneça um secreto se você quiser verificar se as notificações que você recebe estão vindo do Roblox. Para mais informações, see Verificando a Segurança do Webhook.
    4. Gatilhos — Escolha um ou mais gatilhos da lista de gatilhos suportados Eventos para os quais você deseja receber notificações.
  4. Clique no botão Salvar Alterações .

Configurando URLs de Webhook

Você pode configurar um servidor de ponto de inicializaçã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.
  • Pode lidar com solicitações de POST.
  • Ele pode responder à solicitação com uma resposta de 2XX dentro de 5 segundos.
  • Pode lidar com pedidos HTTPS.

Quando seu ponto de extremo receber um solicitar / pedirPOST, ele 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 na notificação e detalhes específicos relacionados ao tipo de evento na notificações.

Para mais informações do schema das solicitações POST para Manipulador / alça, see the Payload Schema .

Política de Tentativa de Falha de Entrega

Quando uma notificação de webhook falha para alcançar sua URL especificada devido a erros, como a indisponibilidade do ponto de terminação, o Roblox retenta enviar a mensagem para a URL configurada 5 vezes usando um tamanho de janela fixo. Se a notificação ainda falhar após 5 tentativas, o Roblox para de tent

Requisitos de terceiros

As 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 de terceiros. Para as três ferramentas de terceiros suportadas, veja o seguindo:

Testando 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 WebHooks.

  2. Selecione o webhook que você deseja testar na lista de webHooks configurados.

  3. Clique no ícone de lápis ao lado do cabo de web de destino.

    The pencil icon next to an example webhook

  4. 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 aciona a notificações, como mostra o seguinte exemplo de script:

Modelo de Notificação de Exemplo
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 a URL de terceiros para confirmar que o serviço pode receber notificações com sucesso do seu webhook. Se você fornecer uma senha ao configurar o webhook, também gera uma roblox-signature que você pode usar para testar a lógica roblox-signature.

Verificando a Segurança do Webhook

Uma vez que você configura seu servidor para receber os payloads, ele começa a ouvir qualquer payload enviado para o endpoint. Se você definir um secreto ao configurar seu webhook, o Roblox envia uma roblox-signature juntamente com cada notificação de webhook para ajudar a proteger sua segurança de dados. Desta forma, você pode usar o

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 apenas contém o valor de data de envio na hora em que a notificação é enviada:

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

Para verificar uma assinatura:

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

    • t : O valor de data de envio da notificação.
    • v1 : O valor de assinatura gerado usando a configuração de diretrizes de criação fornecida. Você pode extrair esses dois valores usando a função split() ", que separa a string baseado em um delimitador, neste caso, o personagem ,.

  2. Re-criar a string de base de roblox-signature por meio de concatenar:

    1. A data de validação como uma string / cadeia / texto.
    2. O personagem de período . .
    3. A string JSON do corpo da solicitação.

  3. Compute um código de autenticação de mensagem baseado em hash (HMAC) com a função de hash secreta que você definiu durante a configuração como a chave e a string base que você gerou através do passo 2 como a mensagem. Converta o resultado para o formato Base64 para obter a assinatura esperada.

  4. Compare o valor de assinatura extraído ao valor esperado. Se você gerou a assinatura corretamente, o valor deve ser o mesmo.

  5. (Opcional) Para evitar ataques de replay, um tipo de ataque cibernético onde atacantes interceptam e reenviam dados para ganhar acesso não autorizado ou executar ações maliciosas, é útil comparar o valor de data de timestamp extraído com o atual e garantir que ele caia 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 Payload

Quando o evento alvo do seu webhook é acionado, ele envia uma solicitação para a URL do seu webhook, incluindo informações sobre o evento no payload. Todos os payloads de solicitações compartilham o mesmo schema 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 de destino processar e usar os dados.

Os campos de script de carga fixa podem ajudar a manter a consistência em todos os pedidos 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, ele é considerado duplicado.
  2. EventType , string : Uma string representa o tipo de evento para o qual a notificação foi acionada.
  3. EventTime , timestamp : Um tempo de aproximação de quando o evento foi acionado.

Os campos de script de carga de variáveis fornecem flexibilidade para webHooks para acomodar vários tipos de eventos, incluindo:

  1. EventPayload , object : Contém informações específicas para o EventType que desencadeou o webhook. A estrutura do script 0> EventPayload0> varia com base no tipo de evento.

O seguinte exemplo mostra o schema de pagamento do pedido de exclusão direita evento:

Exemplo de Esquema para Solicitação de direito ao esquecimento
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



      ]



   }



}

Gerenciando Notificações

Se você armazenar quaisquer Informações Pessoalmente Identificáveis (IIP) de seus usuários, como seus IDs de loja, você

Se você usar um endpoint personalizado como seu servidor de webhook em vez de uma ferramenta de terceiros, você pode extrair os dados do assunto de dados para a exclusão do webhook e construir sua própria solução de automação. O seguinte código de exemplo fornece uma solução de exemplo e adiciona uma solução de prevenção ao replay de ataques 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')

})