> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/pt-br/guide/account/iot-logic/nodes/webhook-node.md). # Webhook ## Visão geral técnica e recursos {% columns %} {% column width="58.333333333333336%" %} **Webhook** O nó permite o acionamento em tempo real de ações específicas em sistemas externos. Ele envia solicitações HTTP POST para pontos de extremidade especificados ao receber dados de nós conectados. Em seguida, constrói cargas JSON personalizadas com atributos estáticos e dinâmicos e executa chamadas de API para serviços de terceiros. {% endcolumn %} {% column width="41.666666666666664%" %}
{% endcolumn %} {% endcolumns %} O nó amplia os recursos do IoT Logic além do processamento e da transmissão de dados, permitindo integração direta com plataformas de mensagens, sistemas ERM e CRM e aplicativos personalizados para iniciar ações automatizadas com base na configuração do seu fluxo. {% hint style="info" %} Os nós webhook são configurados separadamente para cada fluxo na interface de usuário da plataforma Navixy. Os nós webhook servem como pontos terminais em um fluxo e exigem pelo menos uma conexão de entrada para funcionar. Eles não podem repassar dados para nós subsequentes. {% endhint %}
### Como os nós Webhook funcionam Quando os dados chegam a um nó Webhook por meio de uma conexão de entrada, ele executa imediatamente uma solicitação HTTP POST para o endpoint configurado. O nó: 1. Coleta os valores atuais de todos os atributos dos nós anteriores conectados 2. Substitui referências de atributos dinâmicos (por exemplo, `{{speed}}`) pelos valores reais da mensagem de entrada 3. Constrói a carga JSON completa, preservando a estrutura definida 4. Envia a solicitação HTTP POST com os cabeçalhos especificados para o endpoint de destino 5. Continua sem aguardar uma resposta, permitindo que o fluxo prossiga imediatamente O webhook é disparado uma vez para cada mensagem que o alcança. Se várias ramificações paralelas enviarem dados ao webhook, ele será disparado separadamente para cada mensagem de entrada. Essa execução acontece de forma independente, sem bloquear outros nós no fluxo, garantindo processamento contínuo dos dados independentemente dos tempos de resposta do sistema externo. Cada **Webhook** resultado de acionamento do nó aparece em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md) como um atributo nomeado após o **ID do nó** (exibido na caixa de diálogo de configuração do nó, por exemplo `webhook_1a2b3c4d`). O valor é `0` quando o nó não foi disparado e `1` quando ele já foi disparado, permitindo que você confirme a entrega e diferencie vários nós Webhook no mesmo fluxo. ### Integração com a arquitetura do fluxo Os nós Webhook funcionam como pontos de terminação que convertem dados de dispositivos processados em chamadas de API externas. Em vez de transmitir continuamente todos os dados do dispositivo, como fazem os nós Ponto de Extremidade de Saída, os webhooks executam solicitações de API direcionadas com cargas precisamente configuradas. Essa arquitetura permite: * **Automação orientada a eventos**: Acione fluxos de trabalho externos com base nas condições dos dispositivos, métricas calculadas ou padrões de dados específicos identificados anteriormente no fluxo * **Transmissão seletiva de dados**: Envie apenas os atributos relevantes para sistemas externos, reduzindo a transferência desnecessária de dados e os custos de API * **Execução paralela**: Opera em conjunto com outros nós de saída, permitindo acionamentos simultâneos de webhook e transmissão contínua de dados para diferentes destinos * **Integração multifonte**: Aceita conexões de entrada de várias ramificações paralelas e acessa atributos de todos os nós conectados ### Recursos do nó O **nó Webhook** oferece: * **Execução de HTTP POST**: Envia solicitações HTTP POST personalizadas para qualquer endpoint acessível usando os protocolos HTTP ou HTTPS (HTTPS recomendado) * **Construção dinâmica da carga**: Cria corpos de solicitação JSON combinando valores estáticos com atributos dinâmicos de qualquer parte do fluxo usando `{{attribute_name}}` sintaxe * **Configuração de cabeçalhos personalizados**: Suporta até 10 cabeçalhos HTTP definidos pelo usuário para autenticação e requisitos específicos da API * **Suporte a atributos aninhados**: Faz referência a estruturas complexas de atributos, incluindo objetos e arrays aninhados dentro da carga JSON * **Execução independente**: Dispara sem aguardar respostas ou bloquear o fluxo, permitindo operação confiável independentemente da disponibilidade do sistema externo ## Opções de configuração {% columns %} {% column valign="middle" %} O nó Webhook permite que você defina como o seu fluxo se comunicará com sistemas externos por meio de chamadas de API HTTP. {% endcolumn %} {% column %}
{% endcolumn %} {% endcolumns %} Vamos ver quais elementos este nó usa e o que você pode configurar ao trabalhar com ele. ### Etapas de configuração {% stepper %} {% step %} #### Especifique o nome do nó Insira um nome descritivo que identifique a finalidade do webhook. * Use nomes que indiquem o serviço ou a ação de destino (por exemplo, "Alertas de velocidade do Slack" ou "Criação de tíquete no CRM") * Este nome aparece no diagrama do fluxo para facilitar a identificação {% endstep %} {% step %} #### ID do nó (gerado automaticamente) Abaixo do campo Nome, a caixa de diálogo exibe um **ID do nó** (por exemplo, `webhook_1a2b3c4d`). Este campo é somente leitura — você não pode editar nem definir seu valor. * O ID é gerado automaticamente quando o nó é criado e permanece o mesmo durante toda a vida útil do nó * Use-o para diferenciar os resultados deste nó dos de outros nós Webhook em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md), onde ele aparece como um atributo mostrando `0` (não disparado) ou `1` (disparado) {% endstep %} {% step %} #### Configure a URL do endpoint Insira a URL completa para a qual as solicitações POST são enviadas. * Inclua o protocolo: `http://` ou `https://` (HTTPS fortemente recomendado) * Certifique-se de que a URL aponte para um endpoint de API válido que aceite solicitações POST * Exemplo: `https://api.example.com/v1/webhooks/device-alerts` {% endstep %} {% step %} #### Definir cabeçalhos HTTP Adicione quaisquer cabeçalhos exigidos pela sua API de destino. 1. Clique em **Adicionar cabeçalho** para criar pares chave-valor de cabeçalho\ Todos os cabeçalhos são configurados pelo usuário, incluindo Content-Type. Os cabeçalhos comuns incluem: * `Content-Type: application/json` (obrigatório para cargas úteis JSON) * `Autorização: Bearer ` (para autenticação da API) * Chaves de API personalizadas ou cabeçalhos de autenticação conforme os requisitos do serviço 2. Clique no ícone de exclusão para remover cabeçalhos individuais {% hint style="info" %} Há suporte para no máximo 10 cabeçalhos {% endhint %} {% endstep %} {% step %} #### Monte o corpo da requisição Mude para a **Corpo** aba e defina a estrutura JSON que é enviada para o endpoint: * Insira uma sintaxe JSON válida no campo Body * Use `{{attribute_name}}` para referenciar qualquer atributo dos nós conectados * Suporta estruturas JSON aninhadas e arrays * As referências a atributos funcionam com caminhos aninhados (por exemplo, `{{location.latitude}}`) * Se um atributo referenciado for nulo ou não existir, o valor `nulo` é enviado no JSON **Exemplo de corpo do webhook com atributos dinâmicos:** ```json { "alert_type": "speed_violation", "device_id": "{{device_id}}", "current_speed": "{{speed_mph}}", "threshold_exceeded": 80, "location": { "lat": "{{latitude}}", "lng": "{{longitude}}" }, "timestamp": "{{message_time}}", "Motorista": "{{hardware_key}}" } ``` {% endstep %} {% step %} #### Salve sua configuração Clique em **Aplicar alterações** para armazenar as configurações do nó do webhook. {% endstep %} {% endstepper %} ## Comportamento de execução do webhook O webhook é executado sem aguardar respostas do endpoint externo. O sucesso ou a falha da solicitação do webhook não afeta a continuidade da operação do fluxo nem bloqueia outros Nós de processarem os dados. {% hint style="danger" %} Atualmente, a execução do webhook não inclui tentativas automáticas, registro de tentativas falhas ou tratamento de respostas. Se um endpoint retornar um erro ou expirar o tempo limite, o webhook será acionado novamente na próxima mensagem recebida. Atualizações futuras podem incluir limites de taxa definidos pelo destino e enfileiramento de solicitações. {% endhint %} ### Webhook vs transmissão contínua de dados **nó Webhook** difere fundamentalmente de **Nó de Ponto de Extremidade de Saída** em propósito e padrão de execução: | nó Webhook | Nó de Ponto de Extremidade de Saída | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Executa chamadas de API discretas em cada mensagem, enviando cargas úteis personalizadas que você define. Ideal para acionar ações externas, enviar notificações ou transmitir dados seletivos para APIs REST. | Mantém fluxos contínuos de dados via MQTT, transmitindo dados completos do dispositivo no formato Navixy Generic Protocol. Projetado para coleta contínua de telemetria e monitoramento em tempo real. | Escolha webhooks quando precisar acionar automações externas ou enviar apenas atributos específicos para endpoints de API. Use endpoints de saída para fluxos contínuos de dados para plataformas de análise ou sistemas de monitoramento. Ambos podem coexistir no mesmo fluxo. ### Integração com sistemas externos Nós de webhook se destacam ao acionar ações orientadas a eventos em sistemas que fornecem APIs REST. Os padrões comuns de integração incluem: * **Plataformas de mensagens**: Envie notificações para Slack, Microsoft Teams, WhatsApp ou Telegram quando as condições do dispositivo atenderem a critérios específicos * **Sistemas ERP**: Sincronize os dados do dispositivo com plataformas de planejamento de recursos empresariais para atualizar níveis de estoque, acionar fluxos de trabalho de compras ou registrar o uso de equipamentos para agendamento de manutenção * **Sistemas de chamados**: Crie automaticamente tickets de suporte ou solicitações de serviço em plataformas de CRM quando problemas do dispositivo forem detectados * **Serviços de alerta**: Acione notificações por SMS, e-mail ou push por meio de serviços como Twilio, SendGrid ou Firebase quando os limites forem excedidos * **Automação de negócios**: Inicie fluxos de trabalho em ferramentas como Zapier, Make (Integromat) ou n8n com base na telemetria do dispositivo * **Sistemas de telemática**: Acione ações específicas ou automações em soluções de telemática de terceiros com base em dados processados, permitindo fluxos de trabalho orientados a eventos, como recálculos de rota, notificações ao motorista ou atualizações de status em sistemas externos de gestão de frotas * **Aplicações personalizadas**: Ative a lógica de negócios proprietária publicando eventos do dispositivo em APIs internas ## Perguntas frequentes #### Como faço para acionar webhooks apenas sob condições específicas? Use o cabeçalho **Lógica** nó para implementar lógica condicional antes do webhook. O **Lógica** nó pode avaliar atributos do dispositivo e encaminhar dados de rota ao webhook somente quando as condições forem atendidas. Para detalhes, consulte [Lógica](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node.md). #### Posso usar vários nós Webhook no mesmo fluxo? Sim. Inclua vários **nós Webhook** com configurações diferentes para acionar vários sistemas externos com base nos mesmos dados do dispositivo. Cada webhook é acionado independentemente quando recebe dados. #### O que acontece se a solicitação do webhook falhar? O webhook é acionado sem aguardar uma resposta e não tenta novamente automaticamente. Se o endpoint externo estiver indisponível ou retornar um erro, o fluxo continua processando normalmente. O webhook tenta ser acionado novamente quando a próxima mensagem chega. Atualmente, não há registro das tentativas de webhook com falha. #### Como faço a autenticação com APIs externas? Configure a autenticação inteiramente por meio de cabeçalhos personalizados. Abordagens comuns: * **Tokens Bearer**: Adicione o cabeçalho `Authorization` com o valor `Bearer seu_token_aqui` * **Chaves de API**: Adicione cabeçalhos personalizados conforme especificado pelo provedor da sua API * **Autenticação básica**: Adicione o cabeçalho `Authorization` com o valor `Basic credenciais_codificadas_em_base64` Inclua sempre `Content-Type: application/json` como cabeçalho ao enviar cargas JSON. #### Posso referenciar atributos de vários nós conectados? Sim. O nó de webhook pode acessar atributos de qualquer nó conectado a ele, incluindo ramificações paralelas. Se vários nós enviarem dados para o webhook, ele será acionado uma vez para cada mensagem recebida e poderá referenciar atributos do caminho de origem dessa mensagem. #### Quais dados posso incluir no corpo do webhook? Você pode incluir qualquer combinação de: * Valores estáticos definidos diretamente na sua configuração JSON * Atributos dinâmicos do fluxo usando `{{attribute_name}}` sintaxe * Atributos aninhados de estruturas de dados complexas * Atributos calculados em **nós Iniciar Atributo** ou processados por meio de **Lógica** nós O corpo deve ser um JSON válido. Se um atributo referenciado não existir ou contiver um valor nulo, `nulo` é enviado no JSON. #### Como posso testar minha configuração de webhook? Abra [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md) para o fluxo e selecione o dispositivo acionador. Procure o atributo correspondente ao ID deste nó: o valor dele muda para `1` toda vez que o webhook é acionado, `0` caso contrário. Isso confirma que o webhook foi acionado sem necessidade de acesso ao endpoint de destino. Para verificar se o destino realmente recebeu a carga útil esperada, considere usar serviços de teste de webhook como webhook.site ou RequestBin durante o desenvolvimento para inspecionar as solicitações exatas que estão sendo enviadas. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/user/pt-br/guide/account/iot-logic/nodes/webhook-node.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.