Webhooks

Um webhook é um URL especificado pelo parceiro em que a plataforma RBM publica mensagens e eventos. Esse URL funciona como um endpoint que recebe solicitações POST HTTPS com dados sobre os eventos. Isso significa que os dados são enviados com segurança para seu aplicativo por HTTPS.

Um URL de webhook pode ser parecido com este: https://[your company name].com/api/rbm-events. Depois de configurar o webhook, você poderá começar a receber mensagens e eventos.

Webhooks do parceiro e do agente

É possível configurar o webhook no nível do parceiro ou do agente.

• O webhook do parceiro se aplica a todos os agentes que você mantém. Se os agentes tiverem um comportamento semelhante ou se você tiver apenas um agente, use o webhook do parceiro.
• Os webhooks de agentes são aplicados a agentes individuais. Se você opera vários agentes com comportamentos distintos, é possível definir um webhook diferente para cada agente.

Se você tiver configurado um webhook do parceiro e um webhook do agente, o webhook do agente terá precedência no agente específico, enquanto o webhook do parceiro será aplicado a todos os agentes que não tiverem um webhook próprio.

Configurar um webhook do agente

Observação: para criar uma integração de webhook usando a API RBM Management, consulte a documentação Criar uma integração de webhook.

Você recebe as mensagens enviadas ao seu agente no webhook do parceiro. Se você quiser que as mensagens de um agente específico cheguem a um webhook diferente, defina um webhook do agente.

1. Abra o console do desenvolvedor de comunicações comerciais e faça login com sua Conta do Google do parceiro RBM.
2. Clique no seu agente.
3. Clique em Integrations.
4. Em Webhook, clique em Configurar.
5. Em URL do endpoint do webhook, insira o URL do webhook que começa com "https://".
6. Anote o valor de clientToken. Você precisa dele para verificar se as mensagens que você recebe são do Google.

7. Configure seu webhook para aceitar uma solicitação POST com o parâmetro clientToken especificado e envie uma resposta 200 OK com o valor de texto simples do parâmetro secret como o corpo da resposta.

   Por exemplo, se o webhook receber uma solicitação POST com o seguinte conteúdo do corpo

   {
     "clientToken":"SJENCPGJESMGUFPY",
     "secret":"1234567890"
   }
   

   O webhook precisa confirmar o valor clientToken e, se clientToken estiver correto, retornar uma resposta 200 OK com 1234567890 como o corpo da resposta:

   // clientToken from Configure
   const myClientToken = "SJENCPGJESMGUFPY";
   
   // Example endpoint
   app.post("/rbm-webhook", (req, res) => {
     const msg = req.body;
     if (msg.clientToken === myClientToken) {
         res.status(200).send(msg.secret);
         return;
     }
     res.send(400);
   });
   

8. No console do desenvolvedor, clique em Verificar. Quando o RBM verifica seu webhook, a caixa de diálogo é fechada.

Verificar mensagens recebidas

Como os webhooks podem receber mensagens de qualquer remetente, verifique se o Google enviou mensagens de entrada antes de processar o conteúdo delas.

Para verificar se o Google enviou uma mensagem que você recebeu, siga estas etapas:

1. Extraia o cabeçalho X-Goog-Signature da mensagem. Esta é uma cópia hash codificada em base64 do payload do corpo da mensagem.
2. Decodificar em base64 o payload do RBM no elemento message.body da solicitação.
3. Usando o token de cliente do webhook (especificado ao configurar o webhook) como chave, crie um HMAC SHA512 dos bytes do payload da mensagem decodificada em base 64 e codifique o resultado em base64.
4. Compare o hash X-Goog-Signature com o hash que você criou.
   • Se os hashes forem correspondentes, você terá confirmado que o Google enviou a mensagem.

   • Se os hashes não corresponderem, verifique o processo de hash em uma mensagem conhecida como boa.

     Se o processo de hash estiver funcionando corretamente e você receber uma mensagem que acredita ter sido enviada de forma fraudulenta, entre em contato com nossa equipe.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);
  

Processamento de mensagens

O retorno de qualquer coisa que não seja 200 OK de um webhook é considerado uma falha de envio.

Os desenvolvedores precisam estar cientes de que o envio de mensagens em altas taxas gera notificações de webhook em altas taxas e precisam projetar o código para garantir que possam consumir notificações na taxa esperada. É importante que os desenvolvedores considerem situações que podem causar respostas de falha, incluindo respostas 500 do contêiner da Web, timeouts ou falhas upstream. As coisas a considerar incluem:

• Verifique se as proteções contra DDoS estão configuradas para processar a taxa esperada de notificações de webhook.
• Verifique se recursos como pools de conexões de banco de dados não acabam e produzem timeouts ou respostas 500.

Os desenvolvedores precisam garantir que o processamento de eventos RBM seja realizado de forma assíncrona e não impeça que o webhook retorne 200 OK.

É importante não processar o evento RBM no webhook. Qualquer erro ou atraso durante o processamento pode afetar o código de retorno do webhook:

Comportamento em caso de falha na entrega

O RBM usa um mecanismo de desistência e repetição quando recebe uma resposta diferente de 200 OK de uma chamada de webhook. O RBM vai aumentar o tempo de espera entre as novas tentativas, até um máximo de 600 segundos. As tentativas vão continuar por sete dias, depois disso, a mensagem será descartada.

Implicações dos webhooks no nível do agente

O RBM enfileira mensagens para um parceiro em uma fila. Quando um parceiro usa webhooks no nível do agente, é importante lembrar que a falha de um webhook afeta a entrega para outros webhooks. Os webhooks pertencentes a outros agentes serão chamados durante o período de espera de uma mensagem com falha. No entanto, à medida que as mensagens com falha forem enfileiradas para nova tentativa, as taxas de entrega gerais vão cair e outros agentes serão afetados.

É importante que os desenvolvedores entendam esse modelo e o código de forma adequada, aceitando mensagens e colocando-as em fila para processamento, para minimizar a possibilidade de retornar uma falha.

Próximas etapas

Depois de configurar o webhook, o agente poderá receber mensagens dos dispositivos de teste. Envie uma mensagem para validar sua configuração.