Como utilizar o Webhook

 

Durante a implementação da API poderão existir momentos em que você precisará aguardar alguma ação do cliente antes de prosseguir com seu processo. Suponha que você necessite confirmar se o cliente respondeu a ultima mensagem para poder verificar qual próximo passo do atendimento. Uma prática desaconselhável seria, por exemplo, agendar uma consulta minuto a minuto a API da Huggy para verificar as mensagens enviadas pelo cliente.

Além de desperdiçar recursos de processamento, você também sofreria com o atraso entre o momento real da mensagem enviada pelo cliente e da consulta da API. Isso poderia ser resolvido diminuindo o intervalo entre as consultas, porém dependendo do número de mensagens, este método tornaria-se inviável em pouco tempo.

Para resolver esse problema, inverte-se a responsabilidade da notificação: A Huggy avisará você quando alguma ação ocorrer. Este aviso é realizado através de um HTTP POST que a Huggy faz em uma URL que você pode configurar na plataforma. Estes avisos são chamados de Webhooks.

Como utilizar

Para utilizar o Webhook na Huggy, você precisa registrar a URL do seu site no painel.

  1. Para isso, acesse “Configurações > Integrações > Webhook“.
  2. No campo “URL“, insira o endereço que a Huggy deverá enviar as notificações.
Para conseguir ativar o envio das notificações para seu endereço, você precisará antes configurar sua página para imprimir o token que está disponível na página de configurações do webhook. Somente assim ao salvar a URL no painel, a Huggy conseguirá validar e salvar as configurações do webhook.

Formato e método de envio

Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON, incluindo os seguintes headers:

Content-Type: application/json; charset=UTF-8

Veja abaixo mais detalhes sobre o conteúdo enviado.

A plataforma espera que sua aplicação responda com o código HTTP 2XX (200, 201, etc) em no máximo 20 segundos. Códigos de redirecionamento (3XX) não serão seguidos e serão considerados como falha.

Caso seja necessário, consulte a lista de endereços IP de origem para webhooks.

 

Retentativas

A plataforma Huggy irá efetuar 3 retentativas de envio caso seu sistema esteja fora do ar ou responda com um código HTTP diferente de 2xx. As retentativas são todas enviadas no intervalo de 10 segundos. Depois desse período a requisição é descartada pelo Huggy.

Esteja ciente de que as requisições podem chegar até seu servidor em uma ordem diferente do disparo. Dependendo da ação desejada, recomendamos você faça uma consulta à API no momento em que receber o webhook para saber se as informações recebidas são as mais recentes.

 

Conteúdo da requisição

Como mencionado acima, o conteúdo da requisição estará contido em seu no corpo (body), no formato JSON:

{
"time":1501188213,
"messages":{
"receivedMessage": [{
"id": 999999,
"body": {...},
"is_internal": false,
"is_email": false,
"file": null,
"channel": "widget",

"customer": {
"id": 999999,
"name": "Miqueias Gomes",
"mobile": "5548999999999",
"phone": "5548999999999",
"email": "miqueias.gomes@huggy.io"
},

"chat": {
"id": 9999999,
"channel": "widget",
"situation": "wait_for_chat",
"department": 9999
}
},
"token":"16f64ecc76487a909e278866071b4da8"
}

O conteúdo do atributo body irá depender do tipo de evento enviado e respeitará o mesmo formato da API REST.

Eventos

Os seguintes eventos poderão ser habilitados através do painel de administração:

Evento

Type

Atendimento iniciado

createChat

Mensagem recebida enquanto estiver na fila

receivedMessage

Mensagem recebida independente de estar na fila

receivedAllMessage

Atendimento finalizado

closedChat

Formulário respondido

answeredChatForm

Novo cliente cadastrado

createdCustomer

Novo atendimento via Widget

startedWidgetAttendance

Flow iniciado

startedAutomationFlow

Flow finalizado

finishedAutomationFlow

 

Definindo quais eventos deseja receber:

Para mais informações, consulte nossa documentação do Webhook.

 

Whitelist e segurança

Apesar da plataforma enviar os webhooks através de endereços IP específicos, para garantir a autenticidade das chamadas você deve validar o token que é enviado na chamada com o token do seu lado da aplicação.

Apesar da plataforma suportar o envio para endereços HTTP, recomendamos fortemente que seu endpoint suporte HTTPS. Não é possível configurar portas diferentes de 80 (HTTP) ou 443 (HTTPS).

 

Cross Site Request Forgery (CSRF) em aplicações Rails, Django, etc.

Aplicações desenvolvidas com Ruby on Rails ou Django costumam embutir uma proteção automática contra CSRF. Embora seja uma boa prática, você precisará desabilitar esta proteção no endpoint onde deseja receber as requisições da Huggy.

Rails:

protect_from_forgery :except => :webhook

Django:

@csrf_exempt
def webhook(request):

Para mais informações sobre este assunto, consulte a documentação do Rails ou do Django. Para outros frameworks, busque na documentação pela sigla CSRF.

 

Testes

Antes de apontar o webhook para seu ambiente de produção, recomendamos testá-lo com ngrok ou UltraHook. Estas ferramentas geram uma URL temporária onde você pode inspecionar as requisições realizadas pelo Huggy. Você também pode direcionar testes de webhooks para o ambiente de desenvolvimento em seu próprio computador, utilizando as mesmas ferramentas mencionadas acima, uma opção secundária seria o RequestBin.


O que você achou deste artigo?