Webhooks

Os webhooks conectam o Nodaro aos seus outros sistemas nas duas direções. Um nó Gatilho de webhook (Webhook Trigger) dá a um workflow uma URL que qualquer sistema pode chamar para iniciar uma execução. Um Gatilho agendado (Schedule Trigger) executa o workflow seguindo uma programação, e um nó Saída de webhook (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.

Endpoints

Iniciar um workflow por uma chamada HTTP

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"}'

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

{
  "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.

• 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 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:

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 e Jobs.
• Deixe o workflow avisar você. Termine o workflow com um nó Saída de webhook que envie os resultados para o seu servidor.