Webhooks

Um webhook é um URL especificado pelo parceiro em que a plataforma do RCS for Business posta mensagens e eventos. Esse URL funciona como um endpoint que recebe solicitações HTTPS POST contendo dados sobre os eventos. Isso significa que os dados são enviados ao seu aplicativo com segurança 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ê pode começar a receber mensagens e eventos.

Webhooks de parceiro e de 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 agente se aplicam a agentes individuais. Se você opera vários agentes com comportamentos distintos, pode definir um webhook diferente para cada um deles.

Se você configurou um webhook de parceiro e um de agente, o webhook de agente tem precedência no agente específico, enquanto o webhook de parceiro se aplica a todos os agentes que não têm o próprio webhook.

Configurar um webhook de agente

Você recebe 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 de agente.

  1. Abra o console de desenvolvedor do RCS for Business e faça login com sua conta do Google de parceiro do RCS for Business.
  2. Clique no agente.
  3. Clique em Integrations.
  4. Na seção Webhook, clique em Configurar.
    1. Em Endpoint do webhook, insira o URL do webhook começando com "https://".
    2. Em Token do cliente, especifique o valor clientToken. Ele é necessário para verificar se as mensagens recebidas são do Google.

  5. Configure o webhook para aceitar uma solicitação POST com o parâmetro clientToken especificado e enviar 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"
}

    Em seguida, 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) => {
  // Use the X-Goog-Webhook-Type header to route requests
  const webhookType = req.header('X-Goog-Webhook-Type');

  if (webhookType === 'verification') {
    const msg = req.body;
    if (msg.clientToken === myClientToken) {
        res.status(200).send(msg.secret);
        return;
    }
  }
  res.send(400);
  // handle other webhook types
});

  6. No console de desenvolvedor, clique em Verificar. Quando o RCS for Business verifica o webhook, a caixa de diálogo é fechada.

Identificar tipos de solicitação

Para identificar o tipo de solicitação de todas as solicitações que chegam ao webhook, use o cabeçalho X-Goog-Webhook-Type.

O cabeçalho pode ter os seguintes valores:

  • verification: usado para o processo inicial de verificação de endpoint.
  • message_callback: usado para eventos relacionados a mensagens, como notificações de digitação ou entrega e mensagens recebidas de usuários.
  • agent_callback: usado para eventos administrativos específicos do agente, como mudanças no estado de lançamento do agente.

Verificar mensagens recebidas

Como os webhooks podem receber mensagens de qualquer remetente, verifique se o Google enviou as mensagens recebidas antes de processar o conteúdo da mensagem.

Para verificar se o Google enviou uma mensagem recebida, siga estas etapas:

  1. Extraia o cabeçalho X-Goog-Signature da mensagem. Essa é uma cópia com hash e codificada em base64 do payload do corpo da mensagem.
  2. Decodifique em base64 o payload do RCS for Business no elemento message.body da solicitação.
  3. Usando o token do cliente do webhook (especificado ao configurar o webhook) como uma chave, crie um HMAC SHA512 dos bytes do payload da mensagem decodificada em base64 e codifique o resultado em base64.
  4. Compare o hash X-Goog-Signature com o hash criado.
    • Se os hashes forem iguais, você confirmou que o Google enviou a mensagem.

    • Se os hashes não forem iguais, verifique o processo de hash em uma mensagem conhecida.

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

Node.js

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

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

Gerenciamento de mensagens

Retornar qualquer valor diferente de 200 OK de um webhook é considerado uma falha de entrega.

Os desenvolvedores precisam estar cientes de que o envio de mensagens em taxas altas vai gerar notificações de webhook em taxas altas e precisam criar o código para processar notificações na taxa esperada. É importante que os desenvolvedores considerem situações que possam causar respostas de falha, incluindo respostas 500 do contêiner da Web, tempos limite ou falhas upstream. Algumas coisas a considerar incluem:

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

Os desenvolvedores precisam criar sistemas para que o processamento de eventos RBM ocorra de forma assíncrona e não impeça que o webhook retorne 200 OK.

Processamento assíncrono de webhook

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

Processamento síncrono de webhook

Comportamento em caso de falha na entrega

Se o webhook retornar algo diferente de um status 200 OK, a plataforma do RCS for Business vai usar um mecanismo de espera e nova tentativa para reenviar os dados. Isso significa que o sistema aumenta progressivamente o atraso entre cada tentativa de entrega, atingindo uma frequência máxima de uma nova tentativa a cada 10 minutos para cada mensagem pendente. O ciclo de novas tentativas continua por sete dias, após os quais a mensagem é excluída permanentemente.

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

O RCS for Business enfileira mensagens para um parceiro em uma fila. Todos os agentes em uma única conta de parceiro compartilham uma única fila. Por isso, uma falha em um webhook pode bloquear toda a fila, impedindo que os eventos do usuário para todos os agentes cheguem ao parceiro.

Várias mensagens não confirmadas podem causar um aumento enorme nos eventos de nova tentativa. Por exemplo, se um agente não confirmar 1.600 recibos de entrega e a frequência de novas tentativas atingir o limite de 10 minutos, ele poderá gerar aproximadamente 230.000 erros por dia:

1.600 mensagens × 6 novas tentativas por hora × 24 horas por dia = aproximadamente 230.000 erros por dia

Esse volume de novas tentativas pode bloquear a fila compartilhada do Pub/Sub e causar atrasos significativos no recebimento de eventos do usuário para todas as campanhas de um parceiro.

Práticas recomendadas

Para garantir a confiabilidade do tráfego de produção e evitar bloqueadores de fila, siga estas práticas recomendadas:

  • Retornar 200 OK imediatamente: o webhook precisa receber a mensagem, armazená-la em uma fila local e retornar uma resposta 200 OK em menos de cinco segundos.
  • Desacoplar o processamento: use workers em segundo plano separados para processar a lógica de mensagens da fila local.
  • Monitorar agentes de teste: trate os agentes de desenvolvimento como agentes de produção, porque eles também podem bloquear a fila de parceiros compartilhada se falharem.
  • Contas dedicadas para testes: de preferência, use uma conta de desenvolvedor para agentes de produção e uma conta de desenvolvedor dedicada para agentes de teste.
  • Verificar o tráfego do Google: use o DNS reverso ou o cabeçalho X-Goog-Signature em vez da lista de permissões de IP fixo, já que o Google usa IPs anycast dinâmicos. Para mais informações sobre a verificação manual e a identificação de intervalos de IP do Google, consulte a documentação Verificar solicitações do Google e, especificamente, arquivos JSON para buscadores acionados pelo usuário e buscadores acionados pelo usuário do Google.

Próximas etapas

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

Avançar
Dialogflow