Um webhook é um callback HTTPS criado pelo parceiro que especifica como o agente responde a mensagens e eventos. Depois de configurar seu webhook, comece a receber mensagens e eventos.
Webhooks de parceiros e webhooks de agente
É possível configurar seu webhook no nível do parceiro ou do agente.
- Seu webhook do parceiro se aplica a todos os agentes que você mantém. Se seus 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 comportamento diferente, pode definir um webhook diferente para cada um deles.
Se você tiver configurado um webhook de parceiro e um webhook de agente, o webhook do agente terá precedência sobre o agente específico, enquanto o webhook do parceiro será aplicado a todos os agentes que não tiverem o próprio webhook.
Configurar um webhook de agente
Você recebe mensagens enviadas ao agente no webhook do parceiro. Se você quiser que as mensagens de um agente específico cheguem em um webhook diferente, defina um webhook de agente.
- Abra o Business Communications Developer Console e faça login com sua Conta do Google de parceiro do RBM.
- Clique no seu agente.
- Clique em Integrations.
- Em Webhook, clique em Configurar.
- Em URL do endpoint do webhook, insira o URL do webhook que começa com "https://".
- Anote o valor de
clientToken
. Você precisa dela para verificar se as mensagens que você recebe são provenientes do Google. Configure seu webhook para aceitar uma solicitação
POST
com o parâmetroclientToken
especificado e enviar uma resposta200 OK
com o valor de texto simples do parâmetrosecret
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, seclientToken
estiver correto, retornar uma resposta200 OK
com1234567890
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); });
No Play Console, clique em Verificar. Quando o RBM verifica o webhook, a caixa de diálogo é fechada.
Verificar as mensagens recebidas
Como os webhooks podem receber mensagens de qualquer remetente, verifique se o Google enviou as mensagens de entrada antes de processar o conteúdo delas.
Para verificar se o Google enviou uma mensagem que você recebeu, siga estas etapas:
- Extraia o cabeçalho
X-Goog-Signature
da mensagem. Essa é uma cópia codificada em hash em base64 do payload do corpo da mensagem. - Decodifica em base64 o payload do RBM no elemento
message.body
da solicitação. - Usando o token do cliente do webhook (que você especificou quando configurou o webhook) como uma chave, crie um HMAC SHA512 dos bytes do payload da mensagem decodificada em base64 e codifique o resultado em base64.
- Compare o hash
X-Goog-Signature
com o hash que você criou.- Se os hashes forem correspondentes, isso significa que você confirmou que o Google enviou a mensagem.
Se os hashes não corresponderem, verifique seu 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 maneira 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 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);
Gerenciamento de mensagens
O retorno de algo diferente de 200 OK
de um webhook é considerado uma falha
de entrega.
Os desenvolvedores precisam estar cientes de que o envio de mensagens com taxas altas
gera notificações de webhook em taxas altas 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 de 500
do contêiner da Web, tempos limite ou falhas de upstream. É importante
considerar estes itens:
- Verifique se as proteções contra DDoS estão configuradas para processar a taxa esperada de notificações de webhook.
- Verifique se os recursos, como pools de conexões de banco de dados, não ficam sem tempo e
produzem tempos limite ou respostas
500
.
Comportamento em caso de falha na entrega
O RBM usa um mecanismo de espera e nova tentativa quando recebe uma resposta diferente de
200 OK
de uma chamada do webhook. O RBM aumenta o tempo de espera entre
novas tentativas até um máximo de 600 segundos. As suspensões continuarão por sete dias. Após esse período, a mensagem será descartada.
Implicações dos webhooks no nível do agente
O RBM coloca as mensagens de um parceiro na fila em uma fila. Quando um parceiro usa webhooks no nível do agente, é importante ter em mente que a falha de um webhook afeta a entrega para outros webhooks. Os webhooks de outros agentes serão chamados durante o período de espera de uma mensagem com falha, mas, quando as mensagens com falha entrarem em fila para nova tentativa, as taxas gerais de entrega cairão e outros agentes serão afetados.
É importante que os desenvolvedores entendam esse modelo e código da maneira adequada, o máximo possível, aceitando mensagens e colocando-as em fila para processamento, a fim de minimizar a oportunidade 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.