# Webhooks

> Inicie workflows de qualquer sistema pela URL de um Gatilho de webhook, agende-os pela API e envie os resultados ao seu servidor com a Saída de webhook.

Source: https://nodaro.ai/pt-BR/docs/developers/api/webhooks

Os **webhooks** conectam o Nodaro aos seus outros sistemas nas duas direções. Um nó [**Gatilho de webhook** (Webhook Trigger)](https://nodaro.ai/docs/nodes/automate/webhook-trigger) dá a um workflow uma URL que qualquer sistema pode chamar para iniciar uma execução. Um [**Gatilho agendado** (Schedule Trigger)](https://nodaro.ai/docs/nodes/automate/schedule-trigger) executa o workflow seguindo uma programação, e um nó [**Saída de webhook** (Webhook Output)](https://nodaro.ai/docs/nodes/publish/webhook-output) envia os resultados de uma execução para o seu servidor. O Nodaro não chama você de volta por conta própria: para saber que uma execução terminou, consulte-a periodicamente ou termine o workflow com um nó Saída de webhook.

Workflow: Um sistema externo chama a URL do Gatilho de webhook, o Gerar imagem é executado, e a Saída de webhook envia a URL da imagem para o seu servidor.

- Gatilho de webhook → Gerar imagem (prompt)
- Gerar imagem → Saída de webhook

## Endpoints
| Método | Caminho | O que faz |
| --- | --- | --- |
| `POST` | `/v1/webhooks/:token` | Inicia uma execução. Pública: o token no caminho é a credencial. |
| `GET` | `/v1/workflows/:id/triggers` | Os gatilhos de um workflow, com a URL e o token de cada webhook. |
| `PATCH` | `/v1/workflow-triggers/:id` | Pausa ou retoma um gatilho com `isActive`, ou muda a `config` de um agendamento. |
| `POST` | `/v1/workflow-triggers` | Cria um gatilho manualmente, sem vínculo com nenhum nó. |
| `POST` | `/v1/workflows/:id/sync-triggers` | Registra de novo os nós de gatilho de um workflow a partir da versão salva. |

## Iniciar um workflow por uma chamada HTTP
### Adicionar um Gatilho de webhook
Adicione um nó [Gatilho de webhook](https://nodaro.ai/docs/nodes/automate/webhook-trigger) ao workflow. Em **Parâmetros de saída**, adicione um parâmetro para cada valor que quem chama vai enviar. Cada parâmetro tem um **Nome**, que corresponde a uma chave do corpo JSON da requisição, e um **Tipo**: `text`, `imageUrl`, `videoUrl` ou `audioUrl`. Conecte os parâmetros aos nós que devem usá-los.

### Salvar o workflow
Salvar cria o endpoint: o Nodaro gera um token de 32 bytes e registra `POST /v1/webhooks/<token>`. Isso acontece seja qual for a forma de salvar o workflow: pelo editor, pela API, pelo SDK, por uma importação ou pelo MCP. O token é gerado uma vez e depois mantido, então a URL que você passa a um sistema externo continua válida em todos os salvamentos seguintes. Remover o nó invalida a URL de vez.

### Ler a URL
`GET /v1/workflows/<id>/triggers` retorna os gatilhos do workflow, incluindo o `webhookUrl` e o `webhookToken` de cada webhook. `webhookUrl` é um caminho, `/v1/webhooks/<token>`, então coloque o endereço do seu Nodaro na frente dele. O gatilho cujo `config.nodeId` é o ID do nó pertence a esse nó Gatilho de webhook. A lista mostra só os gatilhos dos workflows que são seus.

No editor, o painel de configurações do nó mostra o mesmo endereço completo em **URL do webhook**, com um botão para copiar.

### Chamar a URL
Envie um `POST` com um corpo JSON. Não é preciso cabeçalho `Authorization`: o token na URL é a credencial.

```bash
curl -s -X POST "https://app.nodaro.ai/v1/webhooks/$WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse in a storm", "imageUrl": "https://example.com/lighthouse.jpg"}'
```

O corpo vira o payload do gatilho. Cada parâmetro lê a chave de mesmo nome, e o tipo dele direciona o valor: um `imageUrl` alimenta entradas de imagem, e um `videoUrl` alimenta entradas de vídeo.

Cada gatilho de webhook aceita 10 requisições por minuto. O limite é separado dos limites dos seus tokens de API.

Exemplos comuns de quem chama: um sistema de pagamentos que inicia um vídeo de onboarding quando um cliente se cadastra, ou um repositório de código que pede um resumo das notas de versão. Também pode ser um sistema de conteúdo que publica um novo artigo ou uma ferramenta de automação no-code.

### O que uma execução por gatilho executa
- **Um gatilho conectado a algo executa só o ramo dele:** os nós seguintes ao gatilho, mais todos os nós de que esses nós precisam como entrada.
- **Um gatilho sem nenhuma conexão executa o workflow inteiro.**
- **Assim, um workflow pode ter vários gatilhos**, cada um iniciando o próprio ramo.
- **“Conectado” significa qualquer coisa que alimente outro nó:** uma conexão desenhada, um nó dentro de um **Grupo** (Group) ou um mapeamento de campo.
- **As execuções pelo editor, pela API e por apps publicados não são limitadas pelos gatilhos.** Elas executam o que sempre executam.

Um gatilho criado manualmente pela API não indica nenhum nó. Nesse caso, o Nodaro usa o único Gatilho de webhook do canvas; se houver dois, o workflow inteiro é executado.

### Manter a URL em segredo
O token é a única credencial, então quem tiver a URL pode iniciar execuções e gastar os seus créditos. Em um workflow no espaço de trabalho de uma organização, as execuções são pagas pelo orçamento do espaço de trabalho: qualquer pessoa com quem você compartilhar a URL pode gastar os créditos da turma ou da equipe.

Toda execução automática, seja de um webhook, de um agendamento ou do Telegram, verifica primeiro se quem criou o gatilho ainda pode executar o workflow. Quando essa pessoa não pode mais, porque uma permissão foi revogada, uma participação foi suspensa ou o espaço de trabalho foi arquivado, a automação para. O histórico de execuções do workflow então mostra uma entrada com falha e o código `run_requires_authenticated_member`.

## Gerenciar gatilhos pela API
Os nós de gatilho se registram sozinhos quando o workflow é salvo. Quatro rotas os gerenciam diretamente:

- **`GET /v1/workflows/<id>/triggers`** lista os gatilhos de um workflow.
- **`PATCH /v1/workflow-triggers/<id>`** com `{ "isActive": false }` pausa um gatilho, e `true` o retoma. Em um gatilho que pertence a um nó, o próximo salvamento aplica de novo a chave liga/desliga do próprio nó, então use essa chave do nó para tudo o que deve permanecer. Uma `config` que você envia é mesclada à que está salva: envie só o que muda. O vínculo do gatilho com o nó e a contagem de execuções dele são mantidos.
- **`POST /v1/workflows/<id>/sync-triggers`** registra de novo os nós de gatilho do workflow a partir da versão salva. O editor chama essa rota depois de cada salvamento, e qualquer pessoa com acesso de edição pode chamá-la. Ela responde `{ "data": { "synced": …, "created": …, "updated": …, "removed": … } }`.
- **`POST /v1/workflow-triggers`** cria um gatilho que não pertence a nenhum nó, então salvar o workflow nunca o altera nem o remove. Criar um gatilho exige a mesma permissão de executar o workflow, porque um gatilho é uma execução sem ninguém acompanhando.

## Agendamentos
Um [Gatilho agendado](https://nodaro.ai/docs/nodes/automate/schedule-trigger) executa um workflow seguindo uma programação. Um agendamento é uma lista de **regras**, e o workflow é executado sempre que alguma regra corresponde ao minuto atual.

### Ativar um agendamento
Um nó Gatilho agendado só dispara enquanto os dados dele dizem `"active": true`, a chave liga/desliga do nó. Um nó gravado pela API, pelo SDK ou pelo MCP sem `active` é registrado como **pausado**. A chave do editor e o botão **Schedule** dele definem o mesmo campo. Uma exportação de template nunca leva esse campo, então um agendamento importado sempre começa pausado.

### Criar um agendamento manualmente
```json
{
"workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"type": "schedule",
"config": {
"rules": [
{ "kind": "days", "every": 1, "hour": 9, "minute": 0 },
{ "kind": "weeks", "every": 2, "weekdays": [1, 3], "hour": 18, "minute": 30 }
],
"timezone": "Asia/Jerusalem"
}
}
```

Envie com `POST /v1/workflow-triggers`. Um nó Gatilho agendado guarda a `config` nesse mesmo formato.

| Campo de `config` | Significado |
| --- | --- |
| `rules` | Uma ou mais regras. O workflow é executado quando alguma regra corresponde. |
| `timezone` | O relógio em que as regras são lidas, como um nome de fuso, por exemplo `Asia/Jerusalem`. UTC quando omitido. |
| `maxExecutions` | Interrompe as execuções depois desse número. O agendamento continua registrado: aumente ou limpe o número para continuar. |

| `kind` | Campos | Executa |
| --- | --- | --- |
| `minutes` | `every` de 1 a 59 | No minuto 0, N, 2N e assim por diante, a cada hora |
| `hours` | `every` de 1 a 23, `minute` | Na hora 0, N, 2N e assim por diante, todo dia, nesse minuto |
| `days` | `every` de 1 a 31, `hour`, `minute` | A cada N dias do calendário, nesse horário |
| `weeks` | `every` de 1 a 52, `weekdays` (0 é domingo, 6 é sábado), `hour`, `minute` | Nesses dias da semana, a cada N semanas |
| `months` | `every` de 1 a 12, `dayOfMonth` de 1 a 31, `hour`, `minute` | Nesse dia, ou no último dia do mês quando o mês é mais curto, a cada N meses |
| `cron` | `cron`, uma expressão de 5 campos | Sempre que a expressão corresponde |

- **A contagem de cada N dias, semanas ou meses parte de um início fixo**, e as semanas começam na segunda-feira, então salvar de novo nunca muda os dias em que um agendamento é executado.
- **Em uma regra `cron`, todos os campos precisam corresponder**, tanto o dia do mês quanto o dia da semana, enquanto algumas ferramentas de cron aceitam qualquer um dos dois. `7` significa domingo, assim como `0`.
- **Valores fora da faixa retornam `400`**, assim como um fuso horário que o servidor não consegue ler.
- **As formas antigas ainda funcionam** em gatilhos que você cria manualmente: um `interval` como `5m`, `1h` ou `1d`, ou uma string `cron`. Um nó Gatilho agendado salvo com elas é convertido em regras.

### Como os agendamentos disparam
- O servidor verifica os agendamentos uma vez por minuto e executa um workflow quando uma das regras dele corresponde a esse minuto.
- Um minuto nunca dispara duas vezes, nem com uma reinicialização ou uma mudança de horário. Um minuto que o relógio pula é ignorado naquele dia.
- Se a execução anterior do workflow ainda estiver em andamento, aquele minuto é ignorado.
- Um nó que não pode ser executado fica **suspenso**, por exemplo com uma regra `cron` sem expressão ou um fuso horário ilegível. Nada é adivinhado: corrija o nó e salve de novo.

## Enviar resultados para o seu servidor
Um nó [Saída de webhook](https://nodaro.ai/docs/nodes/publish/webhook-output) envia o resultado que chega até ele, com os parâmetros que você configura, para a sua URL como uma requisição `POST`. Os parâmetros dele têm os mesmos tipos dos parâmetros do gatilho: `text`, `imageUrl`, `videoUrl` e `audioUrl`. Os valores de mídia são URLs de arquivos armazenados pelo Nodaro, que o seu servidor pode baixar.

Se o seu endpoint responder com um erro, o nó falha, e o erro aparece no histórico da execução. Use uma URL `https`.

### Enviar uma chave com a requisição
Muitos endpoints só aceitam uma requisição com uma chave em um cabeçalho. Salve o nome do cabeçalho e a chave uma vez como uma **credencial** no app web, em **Integrações › Credenciais HTTP**, e escolha essa credencial no nó. A chave nunca entra no workflow, em uma exportação nem em um template.

Ao salvar uma chave, você escolhe quem pode usá-la:

| Escolha | Funciona em |
| --- | --- |
| **Qualquer endereço** (uma credencial não vinculada) | Execuções que você mesmo inicia: uma execução pelo editor e um agendamento que você configura no editor. |
| **Apenas um endereço** (uma credencial vinculada) | Todas as execuções, mas só para esse endereço, ou para caminhos abaixo dele quando você permite. |

As execuções iniciadas com um token de API ou um token OAuth, por um gatilho de webhook, por um agendamento criado pela API ou a partir de um app publicado não são suas, mesmo que sejam executadas em seu nome. **Para essas execuções, vincule a credencial**: uma credencial não vinculada faz o nó falhar com uma mensagem clara, em vez de enviar. Uma credencial vinculada só é enviada quando a URL do nó corresponde ao endereço, um redirecionamento para outro endereço não é seguido, e a chave nunca é enviada por `http` simples.

Com uma credencial anexada, o nó não guarda nem mostra o corpo da resposta do seu endpoint, só o código de status. As credenciais só são gerenciadas no app web: as rotas de credenciais retornam `403 in_app_only` para tokens. Publicar um app ou compartilhar um workflow para que outras pessoas o executem retorna `409 credential_unbound` até que toda credencial que ele envia, inclusive dentro de sub-workflows, esteja vinculada a um endereço para o qual o nó envia.

## Sem callbacks nas execuções pela API
Uma execução que você inicia pela API não chama uma URL quando termina. Você tem dois jeitos de saber o resultado:

- **Consulte periodicamente.** Acompanhe a execução com `GET /v1/workflow-executions/:id`, ou o job de um único nó com `GET /v1/jobs/:id/status`. Veja [Execuções](https://nodaro.ai/docs/developers/api/executions) e [Jobs](https://nodaro.ai/docs/developers/api/jobs).
- **Deixe o workflow avisar você.** Termine o workflow com um nó Saída de webhook que envie os resultados para o seu servidor.

## Frequently asked questions

### Como inicio um workflow do Nodaro com um webhook?

Adicione um nó Gatilho de webhook, defina os parâmetros dele e salve o workflow. Salvar cria uma URL no formato POST /v1/webhooks/ seguido de um token. Envie um corpo JSON cujas chaves correspondam aos nomes dos parâmetros, sem nenhuma outra autenticação.

### O Nodaro chama o meu servidor quando uma execução termina?

Não por conta própria. Consulte periodicamente a execução ou os jobs dela, ou termine o workflow com um nó Saída de webhook, que envia os resultados para a sua URL quando a execução chega a ele.

### É seguro compartilhar a URL de um webhook?

Trate a URL como uma senha. O token na URL é a única credencial, então quem tiver a URL pode iniciar execuções e gastar os seus créditos, ou o orçamento do espaço de trabalho. Cada gatilho aceita 10 requisições por minuto.

### Como agendo um workflow pela API?

Salve um nó Gatilho agendado com "active" igual a true nos dados dele, ou crie um agendamento com POST /v1/workflow-triggers e uma config com regras e um fuso horário. O Nodaro verifica cada agendamento uma vez por minuto.

### Por que um Gatilho agendado criado pela API não é executado?

Um Gatilho agendado só é executado enquanto os dados dele dizem que "active" é true. Um nó gravado pela API, pelo SDK ou pelo MCP sem esse campo é registrado como pausado. Defina o campo e salve de novo.