# Gatilho de webhook

> Inicie um workflow a partir de outro app, um formulário ou seu código com um HTTP POST e passe valores à execução, como um prompt ou a URL de uma imagem.

Source: https://nodaro.ai/pt-BR/docs/nodes/automate/webhook-trigger

O nó **Gatilho de webhook** (Webhook Trigger) inicia um workflow quando outro sistema envia uma requisição HTTP POST para o endereço de webhook do próprio workflow. Use-o para executar um workflow a partir de um sistema de gerenciamento de conteúdo, de um formulário, de uma ferramenta de automação ou do seu próprio código. A requisição pode passar valores para a execução, como um prompt ou a URL de uma imagem. O gatilho em si é grátis.

- Found in: Automate › Triggers
- Output: data
- API type: `webhook-trigger`

## Quando usar
- Gerar um vídeo quando o seu sistema de gerenciamento de conteúdo publica um novo artigo.
- Processar uma imagem que outro app envia, como a foto de um produto.
- Iniciar um workflow a partir de qualquer ferramenta de automação ou script que consiga enviar uma requisição HTTP POST.
- Montar um workflow de conteúdo que o seu próprio código controla.

## Início rápido
### Adicionar o nó
Pressione Tab no canvas e escolha **Automatizar › Gatilhos › Gatilho de webhook**.

### Definir os valores esperados
No painel de configurações, em **Parâmetros de saída**, clique em **Adicionar** para cada valor. Dê a cada parâmetro um nome igual a uma chave do corpo JSON e um tipo: **Texto**, **URL da imagem**, **URL do vídeo** ou **URL do áudio**. Cada parâmetro vira uma saída do nó.

### Montar o ramo
Conecte as saídas aos nós que usam os valores e monte o resto do workflow depois deles.

### Salvar o workflow
Salvar cria o endereço do webhook. Selecione o nó: o painel de configurações dele mostra o endereço completo em **URL do webhook**. Clique no botão de copiar ao lado.

### Enviar uma requisição
Faça um POST de um corpo JSON para o endereço. O workflow é executado com os valores do corpo.

Workflow: Um sistema de conteúdo envia um prompt e a URL de uma imagem, o Gerar vídeo transforma os dois em um clipe e a Saída de webhook envia o vídeo pronto de volta.

- Gatilho de webhook → Gerar vídeo
- Gerar vídeo → Saída de webhook

## Parâmetros de saída
| Campo | O que faz |
| --- | --- |
| **Nome** | A chave a ler do corpo JSON. O nome `prompt` lê o valor de `"prompt"`. |
| **Tipo** | O que o valor é: **Texto**, **URL da imagem**, **URL do vídeo** ou **URL do áudio**. O tipo diz ao Nodaro como passar o valor para os nós depois do gatilho. |

Cada parâmetro vira uma saída do nó, com o nome do parâmetro, e leva o valor da sua chave como texto. Uma chave que falta no corpo deixa a saída dela vazia.

Sem parâmetros, o nó tem uma única saída, **payload**, que leva o corpo inteiro.

## Enviar uma requisição
Faça um POST de um corpo JSON para o endereço do webhook. As chaves do corpo são os nomes dos seus parâmetros.

```bash
curl -X POST "https://app.nodaro.ai/v1/webhooks/<token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A lighthouse at dawn, slow push-in", "imageUrl": "https://example.com/lighthouse.jpg"}'
```

Em uma instalação self-hosted, use o endereço da sua própria instalação em vez de `https://app.nodaro.ai`.

A resposta diz o que aconteceu:

| Status | Significado |
| --- | --- |
| `202` | A execução começou. O corpo traz o `executionId` da execução. |
| `404` | Nenhum webhook responde neste endereço, por exemplo porque o nó foi excluído. |
| `403` | O gatilho foi pausado pela API. |
| `409` | O workflow já tem uma execução em andamento. O corpo traz o `executionId` dessa execução. |
| `429` | Mais de 10 requisições chegaram em um minuto para este token. |

## O endereço e o token
- **Salvar cria o endereço.** Quando você adiciona o nó e salva o workflow, o Nodaro cria um token aleatório de 64 caracteres e o endereço `POST /v1/webhooks/<token>`. Antes do primeiro salvamento, o painel de configurações diz “Salve o workflow para criar a URL deste gatilho”.
- **Copie no painel de configurações.** Depois de salvar, o painel mostra o endereço completo em **URL do webhook**, com um botão de copiar. Abaixo dele, o token aparece abreviado, com o próprio botão **Copiar**.
- **O nó mostra um endereço abreviado.** No canvas, o nó mostra o endereço só com o início do token, como `…/v1/webhooks/a1b2c3d4••••`. Assim, capturas de tela do canvas não revelam o token.
- **Só o proprietário vê o endereço.** O endereço pertence ao proprietário do workflow. Outras pessoas que podem editar o workflow veem a mensagem sobre salvar no lugar do endereço.
- **O endereço continua o mesmo.** O token é criado uma vez e mantido em todos os salvamentos seguintes, então o endereço que você passou para outro sistema continua funcionando.
- **Excluir o nó desativa o endereço.** Exclua o Gatilho de webhook e salve, e o endereço para de funcionar.
- **Leia o endereço pela API.** `GET /v1/workflows/<id>/triggers` retorna o endereço de cada gatilho como um caminho, `/v1/webhooks/<token>`, e o token dele. O gatilho cujo `config.nodeId` é o ID do nó pertence a este nó.

O endereço é público, e o token é a única proteção dele. Qualquer pessoa que tenha o endereço pode iniciar o workflow, e cada execução é cobrada do proprietário do workflow. Mantenha o endereço em segredo.

## Limites
- **10 requisições por minuto** para cada token. As requisições a mais recebem o status `429`.
- **Uma execução por vez.** Enquanto o workflow tem uma execução em andamento, uma nova requisição recebe o status `409`.

## O que entra em uma execução por webhook
Um gatilho conectado a nós executa só o próprio ramo: os nós depois do gatilho e todos os nós de que eles precisam como entrada. Um gatilho que não está conectado a nada executa o workflow inteiro. Assim, um workflow pode ter vários gatilhos, como um Gatilho de webhook e um [**Gatilho agendado** (Schedule Trigger)](https://nodaro.ai/docs/nodes/automate/schedule-trigger), cada um iniciando o próprio ramo.

Um nó conta como conectado por uma conexão desenhada, por estar dentro de um [**Grupo** (Group)](https://nodaro.ai/docs/nodes/automate/group) que o gatilho alimenta ou por um mapeamento de campo. Uma execução manual no editor, uma execução pela API e uma execução de um app publicado nunca ficam limitadas ao ramo de um gatilho.

## Créditos
O Gatilho de webhook é grátis. Cada execução paga pelos nós que executa, e o valor é cobrado do proprietário do workflow.

## Dicas
- **Use os mesmos nomes.** Use exatamente os nomes de chave que o outro sistema envia, com as mesmas maiúsculas e minúsculas.
- **Teste com uma requisição.** Envie uma única requisição com `curl` antes de conectar um sistema de produção.
- **Envie o resultado de volta.** Termine o workflow com [**Saída de webhook** (Webhook Output)](https://nodaro.ai/docs/nodes/publish/webhook-output) para enviar o resultado ao seu próprio servidor.
- **Execute também com agendamento.** Adicione um [Gatilho agendado](https://nodaro.ai/docs/nodes/automate/schedule-trigger) para executar o mesmo workflow em intervalos de tempo.

Leia [Webhooks](https://nodaro.ai/docs/developers/api/webhooks) para ver a API completa.

## Frequently asked questions

### Como inicio um workflow do Nodaro a partir de outro app?

Adicione um nó “Gatilho de webhook” ao workflow e salve-o. Salvar cria um endereço de webhook. Quando o outro app envia uma requisição HTTP POST com um corpo JSON para esse endereço, o workflow é executado.

### Onde encontro a URL do webhook?

Salve o workflow e selecione o nó “Gatilho de webhook”. O painel de configurações dele mostra o endereço completo em “URL do webhook”, com um botão de copiar. O endereço termina em /v1/webhooks/ seguido do token e continua o mesmo nos salvamentos seguintes. Um código pode lê-lo com GET /v1/workflows/<id>/triggers.

### Como passo um prompt ou uma imagem para o workflow?

No painel de configurações, adicione um parâmetro de saída para cada valor, com um nome igual a uma chave do corpo JSON e um tipo, como “Texto” ou “URL da imagem”. Cada parâmetro vira uma saída do nó, que leva o valor dessa chave.

### O endereço do webhook é seguro?

O token no endereço é a única proteção. Qualquer pessoa que tenha o endereço pode iniciar o workflow, e cada execução é cobrada do proprietário do workflow. Mantenha o endereço em segredo e, para desativá-lo, exclua o nó e salve.

### Quantas requisições um webhook pode receber?

Até 10 requisições por minuto para cada token. Uma requisição que chega enquanto o workflow já tem uma execução em andamento é recusada com o status 409.