# Nó Webhook

{% hint style="danger" %}
**Esta funcionalidade está na fase final de desenvolvimento e testes; estará disponível em breve!** Se desejar saber mais ou tiver perguntas  <a href="https://www.navixy.com/contact/" class="button secondary">Contate-nos!</a>
{% endhint %}

## Visão técnica e capacidades

{% columns %}
{% column width="58.333333333333336%" %}
**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.&#x20;
{% endcolumn %}

{% column width="41.666666666666664%" %}

<figure><img src="https://2540041085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2FUuSyHkYRUOQrXCDYFzVx%2FWebhook-node.webp?alt=media&#x26;token=4969dfcf-0011-48c5-8806-ab7fa6c38b61" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

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.

{% hint style="info" %}
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.
{% endhint %}

<figure><img src="https://2540041085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2FPoVERfiwNrGGDU8vAQH6%2FWebhook-in-flow.webp?alt=media&#x26;token=64c97407-4f67-45af-84b4-e7e3970a9718" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="https://2540041085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2F5pNcE8Jq69yJqOzQIzuf%2Fimage.png?alt=media&#x26;token=3988c1ce-9f09-4fce-933e-8379245de5c2" alt=""><figcaption></figcaption></figure>

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

### Etapas de configuração

{% stepper %}
{% step %}
**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
   {% endstep %}

{% step %}
**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`
   {% endstep %}

{% step %}
**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

{% hint style="info" %}
Máximo de 10 cabeçalhos suportados
{% endhint %}
{% endstep %}

{% step %}
**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:**

```json
{
  "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"
}
```

{% endstep %}

{% step %}
**Salve sua configuração**

Clique **Aplicar** para armazenar as configurações do nó webhook.
{% endstep %}
{% endstepper %}

## 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.

{% 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 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.
{% endhint %}

### 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](https://www.navixy.com/docs/user/pt-br/guide/account/iot-logic/flow-management/logic-node).

#### 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.
