Nó Webhook

Esta funcionalidade está na fase final de desenvolvimento e testes; estará disponível em breve! Se desejar saber mais ou tiver perguntas Contate-nos!

Visão técnica e capacidades

Webhook O nó permite acionar ações específicas em sistemas externos em tempo real. Ele envia requisições HTTP POST para endpoints 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.

O nó estende as capacidades do IoT Logic além do processamento e transmissão de dados, permitindo integração direta com plataformas de mensagens, sistemas ERP e CRM, e aplicações personalizadas para iniciar ações automatizadas com base na configuração do fluxo.

Os nós webhook são configurados separadamente para cada fluxo na interface da plataforma Navixy. 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 passar dados para nós subsequentes.

Como os nós Webhook funcionam

Quando os dados alcançam um nó Webhook por meio de uma conexão de entrada, ele executa imediatamente uma requisição HTTP POST para o endpoint configurado. O nó:

1. Coleta valores atuais para todos os atributos dos nós upstream conectados

2. Substitui referências de atributos dinâmicos (por exemplo, $"speed") por valores reais da mensagem recebida

3. Constrói a carga JSON completa preservando a estrutura definida

4. Envia a requisição HTTP POST com os cabeçalhos especificados para o endpoint de destino

5. Continua sem aguardar resposta, permitindo que o fluxo prossiga imediatamente

O webhook dispara uma vez para cada mensagem que o alcança. Se múltiplos ramos paralelos enviarem dados ao webhook, ele dispara separadamente para cada mensagem recebida. Essa execução ocorre de forma independente, sem bloquear outros nós no fluxo, garantindo processamento contínuo de dados independentemente dos tempos de resposta do sistema externo.

Integração na arquitetura do fluxo

Os nós Webhook funcionam como pontos de término que convertem dados processados do dispositivo em chamadas de API externas. Em vez de transmitir continuamente todos os dados do dispositivo como os nós Output Endpoint, os webhooks executam requisições de API direcionadas com cargas precisamente configuradas. Essa arquitetura possibilita:

• Automações orientadas a eventos: Acione fluxos externos com base em condições do dispositivo, métricas calculadas ou padrões de dados específicos identificados anteriormente no fluxo

• Transmissão seletiva de dados: Envie apenas atributos relevantes para sistemas externos, reduzindo transferência de dados desnecessária e custos de API

• Execução paralela: Operar junto com outros nós de saída, permitindo gatilhos de webhook simultâneos e transmissão contínua de dados para diferentes destinos

• Integração multi-origem: Aceitar conexões de entrada de múltiplos ramos paralelos e acessar atributos de todos os nós conectados

Capacidades do nó

O nó Webhook oferece:

• Execução HTTP POST: Envia requisições HTTP POST personalizadas para qualquer endpoint acessível usando protocolos HTTP ou HTTPS (recomenda-se HTTPS)

• Construção dinâmica de payload: Monta corpos de requisição JSON combinando valores estáticos com atributos dinâmicos de qualquer ponto do fluxo usando $"attribute_name" sintaxe

• Configuração personalizada de cabeçalhos: Suporta até 10 cabeçalhos HTTP definidos pelo usuário para autenticação e requisitos específicos de API

• Suporte a atributos aninhados: Referencia estruturas de atributos complexas, incluindo objetos aninhados e arrays dentro da payload JSON

• Execução independente: Dispara sem aguardar respostas ou bloquear o fluxo, possibilitando operação confiável independentemente da disponibilidade do sistema externo

Opções de configuração

O nó Webhook permite definir como seu fluxo se comunicará com sistemas externos por meio de chamadas HTTP API.

Vamos ver quais elementos este nó utiliza e o que você pode configurar ao trabalhar com ele.

Etapas de configuração

1

Especificar título do nó

Insira um nome descritivo que identifique o propósito do webhook.

1. Use nomes que indiquem o serviço ou ação alvo (por exemplo, "Slack Speed Alerts" ou "CRM Ticket Creation")

2. Esse nome aparece no diagrama do fluxo para fácil identificação

2

Configurar a URL do endpoint

Insira a URL completa para onde as requisições POST serão enviadas.

1. Inclua o protocolo: http:// ou https:// (Recomenda-se fortemente HTTPS)

2. Garanta que a URL aponte para um endpoint de API válido que aceite requisições POST

3. Exemplo: https://api.example.com/v1/webhooks/device-alerts

3

Definir cabeçalhos HTTP

Adicione quaisquer cabeçalhos exigidos pela sua API de destino.

1. Clique Adicionar novo para criar pares chave-valor de cabeçalho

2. Todos os cabeçalhos são configurados pelo usuário, incluindo Content-Type

3. Cabeçalhos comuns incluem:

   1. Content-Type: application/json (obrigatório para payloads JSON)

   2. Authorization: Bearer <token> (para autenticação de API)

   3. Chaves de API personalizadas ou cabeçalhos de autenticação conforme requisitos do serviço

4. Clique no ícone de excluir para remover cabeçalhos individuais

Máximo de 10 cabeçalhos suportados

4

Construir o corpo da requisição

Defina a estrutura JSON que será postada para o endpoint.

1. Insira sintaxe JSON válida no campo Body

2. Use $"attribute_name" para referenciar qualquer atributo de nós conectados

3. Suporta estruturas JSON aninhadas e arrays

4. Referências de atributos funcionam com caminhos aninhados (por exemplo, $"location.latitude")

5. Se um atributo referenciado for nulo ou não existir, o valor null será enviado no JSON

Exemplo de corpo de webhook com atributos dinâmicos:

{
  "alert_type": "speed_violation",
  "device_id": $"device_id",
  "current_speed": $"speed_mph",
  "threshold_exceeded": 80,
  "location": {
    "lat": $"latitude",
    "lng": $"longitude"
  },
  "timestamp": $"message_time",
  "driver": $"hardware_key"
}

5

Salve sua configuração

Clique Aplicar para armazenar as configurações do nó webhook.

Comportamento de execução do Webhook

O webhook é executado sem aguardar respostas do endpoint externo. Sucesso ou falha da requisição do webhook não afeta a continuidade do fluxo nem bloqueia outros nós de processar dados.

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 webhook será disparado novamente na próxima mensagem recebida. Atualizações futuras podem incluir limites de taxa definidos pelo destino e enfileiramento de requisições.

Webhook vs transmissão contínua de dados

nó Webhook difere fundamentalmente do nó Output Endpoint em propósito e padrão de execução:

nó Webhook	nó Output Endpoint
Executa chamadas de API discretas para cada mensagem, enviando payloads personalizados 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 output endpoints para feeds contínuos de dados para plataformas de análise ou sistemas de monitoramento. Ambos podem coexistir no mesmo fluxo.

Integração com sistemas externos

Os nós Webhook se destacam em acionar ações orientadas por eventos em sistemas que fornecem APIs REST. Padrões comuns de integração incluem:

• Plataformas de mensagens: Envie notificações para Slack, Microsoft Teams, WhatsApp ou Telegram quando condições do dispositivo atenderem critérios específicos

• Sistemas ERP: Sincronize dados do dispositivo com plataformas de planejamento de recursos empresariais para atualizar níveis de estoque, acionar fluxos de compras ou registrar uso de equipamentos para agendamento de manutenção

• Sistemas de tickets: Crie automaticamente tickets de suporte ou solicitações de serviço em plataformas CRM quando problemas do dispositivo forem detectados

• Serviços de alerta: Acione SMS, e-mail ou notificações push por meio de serviços como Twilio, SendGrid ou Firebase quando 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 ou automações específicas em soluções de telemática de terceiros com base em dados processados, possibilitando fluxos orientados por eventos como recálculo de rotas, notificações ao motorista ou atualizações de status em sistemas externos de gestão de frotas

• Aplicações personalizadas: Ative lógica de negócio proprietária postando eventos de dispositivo para APIs internas

Perguntas frequentes

Como aciono webhooks apenas sob condições específicas?

Use o nó Logic para implementar lógica condicional antes do webhook. O nó Logic pode avaliar atributos do dispositivo e direcionar dados ao webhook somente quando as condições forem atendidas. Para detalhes, veja documentação do nó Logic.

Posso usar vários nós Webhook no mesmo fluxo?

Sim. Inclua múltiplos nós Webhook com configurações diferentes para acionar vários sistemas externos com base nos mesmos dados do dispositivo. Cada webhook dispara independentemente quando recebe dados.

O que acontece se a requisição do webhook falhar?

O webhook dispara sem aguardar resposta e não realiza tentativas automáticas. Se o endpoint externo estiver indisponível ou retornar um erro, o fluxo continua a processar normalmente. O webhook tentará disparar novamente quando a próxima mensagem chegar. Atualmente, não há registro de tentativas de webhook falhas.

Como me autentico 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 your_token_here

• Chaves de API: Adicione cabeçalhos personalizados conforme especificado pelo seu provedor de API

• Autenticação Basic: Adicione o cabeçalho Authorization com o valor Basic base64_encoded_credentials

Inclua sempre Content-Type: application/json como um cabeçalho ao enviar payloads JSON.

Posso referenciar atributos de múltiplos nós conectados?

Sim. O nó webhook pode acessar atributos de qualquer nó conectado a ele, incluindo ramos paralelos. Se múltiplos nós enviarem dados ao webhook, ele dispara uma vez para cada mensagem recebida e pode referenciar atributos do caminho de origem dessa mensagem.

Que dados posso incluir no corpo do webhook?

Você pode incluir qualquer combinação de:

• Valores estáticos definidos diretamente em 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 Initiate Attribute ou processados por meio de nós Logic

O corpo deve ser JSON válido. Se um atributo referenciado não existir ou contiver valor nulo, null será enviado no JSON.

Como posso testar minha configuração de webhook?

Atualmente, o teste exige implantar o fluxo e verificar os resultados no endpoint de destino. Configure seu webhook, salve o fluxo e envie dados de teste para verificar se o sistema externo recebe a payload esperada. Considere usar serviços de teste de webhook como webhook.site ou RequestBin durante o desenvolvimento para inspecionar as requisições exatas sendo enviadas.