Como utilizar o Webhook

 

Durante a implementação da API, poderão existir momentos em que você precisará aguardar alguma ação ser realizada dentro da plataforma Huggy antes de prosseguir com seu processo. 

Suponhamos que você necessite realizar determinada ação sempre que um novo contato for criado, ou um chat for finalizado na plataforma Huggy. 

Nesse processo, utilizamos o Webhook. O Webhook é um sistema de notificações de eventos capaz de capturar as ações na plataforma Huggy e encaminhar diretamente para o seu sistema. Estas notificações são realizadas através de um HTTP POST que a Huggy faz em uma URL que você pode configurar na plataforma.  

Dividimos esse artigo em 5 tópicos com informações importantes sobre o uso desse recurso:

  • Como acessar e utilizar o webhook na Huggy
  • Testando o webhook
  • Sobre retentativas
  • Whitelist e segurança
  • Cross Site Request Forgery (CSRF) em aplicações Rails, Django, etc.

Como acessar e utilizar o webhook na Huggy

Para ter acesso ao webhook na Huggy, realize o procedimento abaixo:

  1. Dentro da nossa plataforma acesse: Configurações > Integrações > Webhook:
  2. Na tela do recurso webhook, estarão disponíveis os seguintes cards: Informações e Eventos:
    1. Informações: mostra as informações “Código da empresa” (que é o código da sua conta Huggy), o seu Token Webhook e a URL (inserida por você) para onde serão enviadas as notificações dos eventos ocorridos na Huggy. Para alterar o token ou inserir/editar a sua URL, clique no ícone destacado na imagem:

      Ao clicar no ícone indicado acima, você poderá gerar um novo token (caso seja necessário). Aqui também é o local onde você deve inserir a URL onde os eventos serão notificados para que o webhook funcione. Após realizar as ações desejadas, clique em Salvar:
    2. Eventos: aqui você poderá selecionar os eventos dos quais deseja ser notificado na URL do webhook (inserida no processo que descrevemos acima). Atualmente, 11 eventos podem ser notificados:

Testando o Webhook

Antes de colocar o webhook para rodar em seu ambiente de produção, você pode testar o funcionamento dele utilizando um ambiente de testes. Uma ferramenta muito útil para isso é o ngrok

Após fazer o download do ngrok, siga o procedimento abaixo para testar o seu webhook.

  1. Abra o ngrok, digite ngrok http 80 e aperte Enter. Feito isso, aparecerão algumas informações na janela:
    1. Copie o endereço localizado em Web Interface (representado pelo número 1 da imagem) e abra no seu navegador. É por ele que você irá conferir as notificações dos eventos webhook.
    2. O endereço contido em Forwarding (representado pelo número 2 da imagem) é a sua URL. Você deve inseri-la dentro das configurações de webhook na plataforma Huggy (informado no passo 2 da etapa “Como acessar e utilizar o webhook na Huggy”).
  2. Após realizar as configurações acima, sempre que o evento escolhido acontecer na Huggy, a notificação será exibida no endereço que você abriu no navegador.

Lembrando que cada evento presente na Huggy contém um conteúdo específico no BODY da requisição. Clique aqui para conferir na nossa documentação.

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

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.

Sobre 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 em um intervalo de 10 segundos. Depois desse período a requisição é descartada pela 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.

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.


O que você achou deste artigo?


some text
Powered by HelpDocs (opens in a new tab)