WebHooks

Introdução

O Webhook inverte o fluxo de comunicação e permite que sistemas se comuniquem de maneira muito mais ágil e eficiente em resposta a eventos. Roteadores às vezes podem demorar para responder a uma requisição sob algumas condições, como, por exemplo:

• Dispositivo desligado (responderá quando iniciado)
• URL ou senha de Force Connection incorreta
• Ações como reboot ou reset, que levam tempo para ocorrer

Os WebHooks só funcionarão se forem previamente ativados em Clientes API.

Funcionamento

Ao receber uma requisição cadastrada em WebHooks, a API responderá com uma mensagem de confirmação de recebimento, com um número de protocolo que identifica todas as ações relacionadas à requisição.

Número de protocolo

O número de protocolo é um UUID de 32 caracteres, com grupos separados por hífens. Todas as respostas enviadas por meio de WebHooks e que derivem de uma requisição, terão o mesmo UUID.

Métodos Suportados

Os métodos suportados indicam que o WebHook será usado para notificar o resultado de uma ação iniciada pelo IXC/Cliente API:

• devices/parameters/update/: Notifica o status da atualização de parâmetros.
• /api/v1/devices/reboot: Notifica se o comando de reboot (reinicialização) foi executado com sucesso ou falha no dispositivo.

Funcionamento de WebHook

Para ilustrar o funcionamento do WebHook no contexto dos métodos suportados (Update e Reboot), o cenário é ajustado para mostrar a notificação do resultado de uma ação remota, em vez de apenas a queda de conexão.

Cenário 1: Usando um Webhook (Comunicação Ativa) - Notificação de Resultado

Neste modelo, o Servidor (API) notifica o Cliente API/IXC ACS sobre o resultado de uma ação solicitada anteriormente, assim que o dispositivo a conclui.

1. Ação Solicitada: O IXC ACS envia uma requisição para a API solicitando o Reboot do Roteador RTR-42.
2. Configuração: O IXC ACS já informou à API sua Webhook URL para notificações de conclusão (ex: https://monitoramento.ixc.com/resultado).
3. Gatilho: O Roteador RTR-42 conclui a reinicialização (ou a falha ocorre) às 10:07:00h.
4. Ação: A API, instantaneamente, envia uma requisição POST para a Webhook URL com o payload detalhando o resultado (ex: {"protocolo": "UUID-DO-REBOOT", "router_id": "RTR-42", "status": "success", "timestamp": "10:07:00"}).
5. Resultado: O IXC ACS recebe a notificação em tempo real, atualizando o status do comando nos dashboards e prosseguindo com o fluxo de trabalho.

Vantagem Principal: O sistema solicitante (IXC ACS) não precisa esperar nem perguntar, ele é avisado assim que a ação que pode levar tempo é concluída ou falha.

Cenário 2: Usando API Tradicional (Polling) - Verificação de Resultado

Neste modelo, o IXC ACS precisaria verificar ativamente o status do comando no roteador.

1. Ação Solicitada: O IXC ACS envia a requisição de Reboot para a API às 10:05:00h.
2. Configuração: O IXC ACS é configurado para, por exemplo, a cada 5 minutos, perguntar à API sobre o status do comando.
3. Gatilho: O Roteador conclui o reboot às 10:07:00h.
4. Ação:

   • 10:05:00h: Comando de Reboot enviado.

   • 10:07:00h: Reboot concluído. O IXC ACS não sabe disso.

   • 10:10:00h: O IXC ACS faz a primeira requisição de polling para a API: “O comando X foi concluído?” (Recebe o status de sucesso).

5. Resultado: O status do comando só é atualizado no IXC ACS em 10:10:00h, resultando em um atraso de 3 minutos entre a conclusão da ação e a atualização do sistema. Desvantagem Principal: O sistema solicitante fica aguardando (ou checando) por um tempo indeterminado, e a atualização do status depende do intervalo de polling.

Em caso de timeout (1 hora), será enviado um WebHook de erro, porém a ação ainda pode ser executada no dispositivo.

Glossário

Termo	Significado
Timeout	Tempo esgotado
WebHook	Retorno de chamada web (Mecanismo de notificação ativa)

Considerações Finais

É fundamental ativar os WebHooks corretamente e seguir as práticas de segurança na configuração. A compreensão dos métodos suportados e números de protocolo contribui para uma integração eficiente, especialmente quando lidando com ações que podem levar tempo, como reboot e update de parâmetros.

Etiquetas

WebHooks API Integracao Monitoramento Automacao

Leia Também

• Clientes API
• API
• Preset no IXC ACS