Webhooks
Receba eventos assinados job.completed e job.failed no seu servidor, inicie workflows pela URL de um Gatilho de webhook, crie agendamentos e envie resultados.
Os webhooks conectam o Nodaro aos seus outros sistemas nas duas direções. Um endpoint de webhook que você registra recebe um evento assinado sempre que uma das suas tarefas termina, então o seu servidor não precisa consultar periodicamente. Um nó Gatilho de webhook dá a um workflow uma URL que qualquer sistema pode chamar para iniciar uma execução. Um Gatilho agendado executa o workflow seguindo uma programação, e um nó Saída de webhook envia os resultados de uma execução para o seu servidor.
Endpoints
Estas rotas gerenciam os endpoints para os quais o Nodaro envia eventos de tarefa. Veja Receber eventos de tarefa no seu servidor.
| Método | Caminho | O que faz |
|---|---|---|
POST | /v1/webhook-endpoints | Registra um endpoint. A resposta traz o segredo de assinatura dele, uma única vez. |
GET | /v1/webhook-endpoints | Os seus endpoints, do mais novo para o mais antigo. Um segredo nunca é listado. |
GET | /v1/webhook-endpoints/:id | Um endpoint. |
PATCH | /v1/webhook-endpoints/:id | Altera url, events, description ou isActive. |
DELETE | /v1/webhook-endpoints/:id | Exclui o endpoint e o registro de entregas dele. |
POST | /v1/webhook-endpoints/:id/rotate-secret | Substitui o segredo de assinatura, com um período de carência para o antigo. |
GET | /v1/webhook-endpoints/:id/deliveries | O registro de entregas, da mais nova para a mais antiga. |
GET | /v1/webhook-endpoints/:id/deliveries/:deliveryId | Uma entrega. |
POST | /v1/webhook-endpoints/:id/test | Envia um ping de teste. |
Estas rotas iniciam workflows e gerenciam os gatilhos deles. Elas não ficam em /v1/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. |
Receber eventos de tarefa no seu servidor
Registre um endpoint https, e o Nodaro envia a ele um POST sempre que uma das suas tarefas termina. O seu servidor fica sabendo de uma geração concluída sem consultar GET /v1/jobs/:id periodicamente. Cada requisição é assinada com o segredo do próprio endpoint, repetida com espera crescente até o seu servidor responder e anotada no registro de entregas do endpoint.
Registrar um endpoint
curl -s -X POST "https://app.nodaro.ai/v1/webhook-endpoints" \
-H "Authorization: Bearer $NODARO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/nodaro-webhook", "description": "order fulfilment"}'const { data: endpoint, secret } = await client.webhooks.create({
url: "https://example.com/nodaro-webhook",
description: "order fulfilment",
})
// Store `secret` (whsec_...) with your server's config: it is shown only once.
await client.webhooks.test(endpoint.id) // a ping, sent within secondsnodaro webhooks create --url https://example.com/nodaro-webhook
nodaro webhooks test <id> --waitA resposta é 201 com { data, secret }. O segredo começa com whsec_ e aparece só nesta resposta, então guarde-o na hora. events é opcional: um endpoint recebe os dois eventos de tarefa, a menos que events indique um deles.
Um endpoint é lido assim:
{
"id": "3f6c2a1e-8b4d-4c7a-9e1f-2d5b6a7c8e90",
"url": "https://example.com/nodaro-webhook",
"description": "order fulfilment",
"events": ["job.completed", "job.failed"],
"isActive": true,
"disabledReason": null,
"disabledAt": null,
"consecutiveFailures": 0,
"appId": null,
"secretCreatedAt": "2026-10-15T10:00:00Z",
"previousSecretExpiresAt": null,
"createdAt": "2026-10-15T10:00:00Z",
"updatedAt": "2026-10-15T10:00:00Z"
}Eventos
| Evento | Enviado quando |
|---|---|
job.completed | Uma tarefa sua chegou a completed. Uma tarefa retida para revisão (pending_review) envia o evento quando é aprovada. |
job.failed | Uma tarefa sua chegou a failed. |
ping | Só a partir de POST /v1/webhook-endpoints/:id/test. Um endpoint nunca o assina. |
Toda tarefa da sua lista de tarefas conta: uma geração avulsa e a tarefa de cada nó dentro de uma execução de workflow. Uma tarefa cancelada não envia nada, e os status intermediários, como pending e processing, também não. Uma tarefa que falha e depois é concluída envia um evento para cada término. As tarefas dentro da execução de um nó Componente não estão na sua lista de tarefas, então não enviam nada: o nó que iniciou a execução informa por ela.
A requisição
O Nodaro envia um POST com Content-Type: application/json e estes cabeçalhos:
| Cabeçalho | Valor |
|---|---|
Nodaro-Signature | t=<unix seconds>,v1=<hex>. Durante uma rotação de segredo, um v1= para cada segredo. |
Nodaro-Event | job.completed, job.failed ou ping |
Nodaro-Delivery | O ID da entrega, o mesmo em todas as novas tentativas deste evento |
Nodaro-Webhook | O ID do endpoint |
Nodaro-Attempt | 1 na primeira tentativa, depois 2, 3 e assim por diante |
User-Agent | Nodaro-Webhooks/1 |
Só o timestamp e o corpo são assinados. Encaminhe e elimine duplicatas pelo type e pelo id do corpo verificado, nunca pelos cabeçalhos Nodaro-Event ou Nodaro-Delivery.
{
"id": "6f1d0c0e-1c7e-4d0a-9f2b-0a4e2f7b9c11",
"type": "job.completed",
"createdAt": "2026-10-15T10:00:04.512Z",
"data": {
"job": {
"id": "0b9a5c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
"status": "completed",
"progress": 100,
"job_type": "generate-image",
"input_data": { "type": "generate-image", "prompt": "a lighthouse at dusk" },
"output_data": { "imageUrl": "https://cdn.nodaro.ai/images/0b9a5c1d.png" },
"error_message": null,
"error_hint": null,
"credit_status": "committed",
"credits": 40,
"credits_charged": 40,
"credits_held": 40,
"credits_released": 0,
"source": "sdk",
"session_id": null,
"title": null,
"created_at": "2026-10-15T10:00:00.000Z",
"completed_at": "2026-10-15T10:00:04.512Z"
}
}
}idé o ID da entrega. Ele é único para cada evento e endpoint, e o mesmo em todas as novas tentativas, então elimine duplicatas por ele.createdAté quando a tarefa chegou a esse status.data.jobé a tarefa no formato queGET /v1/jobs/:idretorna, como estava na primeira tentativa. As novas tentativas enviam o mesmo corpo, byte por byte.credits_chargedainda pode sernull, comcredit_status: "reserved", quando a cobrança não foi liquidada. Leia a tarefa de novo para ver o valor final. Como emGET /v1/jobs/:id,credits_chargedinclui as etapas que a tarefa executou,credits_heldé a reserva da execução com as reservas das etapas, ecredits_releasedé quanto voltou depois que todas as reservas da execução foram liquidadas (nullaté lá). Veja Créditos de uma tarefa.titleé o nome que o dono deu à tarefa, ounullaté ela receber um.- Um evento tem no máximo 64 KB. Para uma tarefa maior,
input_dataé omitido primeiro, depoisoutput_data, edata.omittedlista o que foi omitido.GET /v1/jobs/:idtem a tarefa inteira. - Um
pingtraz"data": { "webhookId": "<endpoint id>" }.
Verificar a assinatura
v1 é o HMAC-SHA256 de <t>.<raw body>, com o segredo inteiro do endpoint como chave (whsec_..., em UTF-8). Verifique três coisas antes de confiar em uma requisição:
- A assinatura corresponde exatamente aos bytes que você recebeu. Nunca serialize o JSON de novo antes.
- O timestamp é recente. Cinco minutos é a tolerância habitual. A verificação impede que uma requisição capturada seja reenviada depois.
- Você ainda não tratou esse
id.
Com o SDK, o verifyWebhookSignature do @nodaro/sdk faz as verificações. Ele usa só a Web Crypto, então funciona no Node 20 ou mais recente, no Deno, no Bun, no Cloudflare Workers, no Vercel Edge e em navegadores.
import express from "express"
import { verifyWebhookSignature, WebhookSignatureError } from "@nodaro/sdk"
const app = express()
app.post("/nodaro-webhook", express.raw({ type: "application/json" }), async (req, res) => {
try {
const event = await verifyWebhookSignature({
payload: req.body, // the raw bytes
header: req.headers["nodaro-signature"],
secret: process.env.NODARO_WEBHOOK_SECRET!,
toleranceSeconds: 300,
})
if (event.type === "job.completed") {
await saveResult(event.data.job.id, event.data.job.output_data)
}
res.sendStatus(204) // any 2xx within 10 seconds counts as delivered
} catch (err) {
if (err instanceof WebhookSignatureError) return res.status(400).send(err.code)
throw err
}
})verifyWebhookSignature retorna o evento já interpretado ou lança um WebhookSignatureError. O code dele é missing_header, malformed_header, signature_mismatch, timestamp_outside_tolerance, invalid_payload, missing_secret ou crypto_unavailable.
Sem o SDK, no Node:
import { createHmac, timingSafeEqual } from "node:crypto"
// rawBody: the request body as received (a Buffer or a string).
function verify(rawBody: Buffer | string, header: string, secret: string, toleranceSeconds = 300) {
const pairs = header.split(",").map((part) => part.trim().split("=", 2))
const t = pairs.find(([key]) => key === "t")?.[1]
const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest()
const matches = pairs.some(([key, value]) => {
if (key !== "v1") return false
const got = Buffer.from(value, "hex")
return got.length === expected.length && timingSafeEqual(got, expected)
})
return matches && Math.abs(Date.now() / 1000 - Number(t)) <= toleranceSeconds
}Durante o período de carência de uma rotação, o cabeçalho traz um v1= para cada segredo, o novo primeiro. Aceite a requisição quando qualquer um deles corresponder. O registro de entregas guarda o corpo exato de uma entrega que não teve sucesso (requestBody), para que você possa reproduzir uma verificação que falha byte por byte.
Novas tentativas
Qualquer resposta 2xx em até 10 segundos conta como entregue. Qualquer outra coisa faz a tentativa falhar: um 3xx (redirecionamentos não são seguidos), um 4xx, um 5xx, um tempo esgotado ou um endereço que não responde. A entrega é então tentada de novo:
| Depois da tentativa | Próxima tentativa em |
|---|---|
| 1 | 30 segundos |
| 2 | 2 minutos |
| 3 | 10 minutos |
| 4 | 1 hora |
| 5 | 6 horas |
| 6 | 12 horas |
| 7 | 24 horas |
Cada espera varia até 10% para mais ou para menos. Depois da 8ª tentativa, cerca de 43 horas depois da primeira, a entrega falha de vez. Um ping de teste é tentado uma vez só.
- A entrega acontece pelo menos uma vez. Uma nova tentativa pode chegar depois que o seu servidor tratou a primeira, por exemplo quando ele respondeu tarde demais. Elimine duplicatas pelo
idda entrega. - Os eventos podem chegar fora de ordem. Até 5 entregas vão para um endpoint ao mesmo tempo, e 10 para uma conta. Use
createdAte o própriostatusda tarefa, não a ordem de chegada. - Um servidor que não responde nada coloca o endpoint em pausa. Depois de 5 tentativas seguidas sem resposta HTTP, o endpoint pausa por um minuto, o dobro do tempo a cada nova ocorrência, até uma hora. As entregas em espera mantêm as tentativas delas, e qualquer resposta HTTP encerra a pausa.
- Um problema do lado do Nodaro não conta contra você. A entrega espera alguns minutos e é tentada de novo sem gastar uma tentativa. Enquanto isso, a entrada dela no registro mostra
signing_unavailableoujob_unreadable.
Desativação automática
Quando 50 entregas seguidas falham de vez, o Nodaro desativa o endpoint: isActive passa a ser false e disabledReason passa a ser "consecutive_failures". Corrija o receptor, verifique-o com um ping de teste e depois ative o endpoint com PATCH /v1/webhook-endpoints/:id e { "isActive": true }. Isso também zera a contagem, assim como qualquer sucesso.
Enquanto um endpoint está desativado, por você ou pelo Nodaro, nenhum evento é registrado para ele. As entregas que já estavam em espera terminam como failed com error: "endpoint_disabled". Um ping de teste continua sendo enviado.
O registro de entregas
GET /v1/webhook-endpoints/:id/deliveries lista as entregas de um endpoint, da mais nova para a mais antiga, 20 por página por padrão e até 100. Filtre com status (pending, delivered ou failed) e pagine com limit e cursor. A resposta é { data, next }. O registro é guardado por 30 dias.
Cada entrega traz o event, o jobId, o status, as attempts, o último responseStatus do receptor, os primeiros 2 KB do responseBody dele, durationMs, error e, enquanto está pendente, nextAttemptAt. requestBody é o corpo exato enviado, guardado enquanto a entrega está pendente ou depois que ela falha, e null depois de entregue. GET /v1/webhook-endpoints/:id/deliveries/:deliveryId lê uma entrega, por exemplo o ping que um teste colocou na fila.
error é um destes valores:
error | Significado |
|---|---|
http_<status> | O seu servidor respondeu com esse status. |
timeout | Nenhuma resposta em até 10 segundos. |
blocked_address | O endereço não resolve para um endereço público da internet. O Nodaro o recusou antes de conectar. |
connection_refused, connection_reset, tls_error, network_error | A conexão falhou. |
endpoint_disabled | O endpoint foi desativado enquanto a entrega esperava. |
app_revoked | Você revogou o app conectado que registrou o endpoint. |
job_deleted | A tarefa foi excluída antes de poder ser enviada. |
attempts_exhausted | A última tentativa foi interrompida do lado do Nodaro antes de a resposta ser registrada. |
signing_unavailable, job_unreadable | Um problema do lado do Nodaro. A entrega espera e é tentada de novo, sem gastar uma tentativa. |
Trocar o segredo
POST /v1/webhook-endpoints/:id/rotate-secret responde { secret, previousSecretExpiresAt }, e o novo segredo aparece só nesta resposta. O novo segredo assina todas as entregas a partir daí, incluindo as novas tentativas. O segredo substituído continua assinando ao lado dele por gracePeriodSeconds: um dia por padrão e 7 dias no máximo. Isso dá tempo para você atualizar o receptor sem interrupção. Envie { "gracePeriodSeconds": 0 } para encerrar o segredo antigo na hora, por exemplo depois de um vazamento.
Regras e limites
- Só
httpsem um host público. Nada dehttp://, nada delocalhost, nenhum endereço privado, de loopback ou link-local, e nenhum nome que só funciona dentro de uma rede privada, como um que termina em.internalou.local. A URL não pode trazer um nome de usuário nem uma senha. O endereço é resolvido de novo a cada tentativa. Para receber na sua própria máquina, use um túnel e registre o endereçohttpsdele. - Um endpoint por endereço. Registrar o mesmo endereço duas vezes responde
409 url_taken. Em vez disso, assine um endpoint aos dois eventos. - 10 endpoints por conta. O 11º responde
400 limit_reached. - As gravações têm limite de taxa: 30 por minuto para criar, atualizar, excluir e trocar o segredo, e 10 pings de teste por minuto.
- Quem pode gerenciar endpoints: uma sessão com login, um token de API pessoal ou o token de um app conectado com o escopo
jobs:read. Um token pessoal limitado a alguns workflows não pode. - Um endpoint que um app conectado registra (
appIddefinido) recebe só as tarefas que o próprio app enviou, e só enquanto a sua autorização ao app incluirjobs:read. As tarefas de uma execução de workflow que o app iniciou não são incluídas: acompanhe a execução comGET /v1/workflow-executions/:id. O app vê só os endpoints que registrou. Você vê todos e pode excluir qualquer um. - As instalações auto-hospedadas enviam a partir do próprio servidor e precisam de
NODARO_ENCRYPTION_KEY, que o conjunto de serviços do Docker Compose gera. Sem ela, as rotas respondem503 encryption_key_missing. - Não disponível pelo MCP. Registrar um endpoint retorna um segredo de assinatura e configura entregas para a conta inteira, uma ação para um app ou para a CLI, não para um agente de IA.
Outros erros: 400 validation_error para um endereço ou um corpo inválido, 403 insufficient_scope, 404 not_found para um ID que não é seu, e 409 url_invalid para um endpoint cujo endereço guardado as regras não aceitam mais. Altere a url dele antes de ativá-lo ou testá-lo. 409 secret_required significa um endpoint registrado antes de a assinatura existir: troque o segredo dele antes de ativá-lo ou testá-lo.
Iniciar um workflow por uma chamada HTTP
Adicionar um Gatilho de webhook
Adicione um nó Gatilho de webhook 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.
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 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>/triggerslista os gatilhos de um workflow.PATCH /v1/workflow-triggers/<id>com{ "isActive": false }pausa um gatilho, etrueo 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. Umaconfigque 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-triggersregistra 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-triggerscria 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 de agendamento na barra superior dele (Agendamento ativado ou Agendamento desativado) 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.
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. |
retry | Opcional. O Repetir em caso de falha do nó: { afterMinutes, maxAttempts, cheapLanesOnly }. Uma execução agendada que termina como failed ou timed_out é executada de novo afterMinutes depois de terminar (de 5 a 1.440, padrão 30), até maxAttempts vezes (de 1 a 5, padrão 3). Com cheapLanesOnly (padrão true), as chamadas de modelo da execução e das repetições dela não passam para o serviço direto do fabricante do modelo. Um campo omitido assume o padrão. Omita retry para não repetir; em um PATCH, "retry": null desativa a repetição. Veja Gatilho agendado. |
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.7significa domingo, assim como0. - Valores fora da faixa retornam
400, assim como um fuso horário que o servidor não consegue ler ou um valor deretryfora da faixa. - Uma execução de repetição aparece em
GET /v1/workflows/<id>/executionscomretry: { "attempt": 1, "maxAttempts": 3, "retryOf": "<failed execution id>" }. - As formas antigas ainda funcionam em gatilhos que você cria manualmente: um
intervalcomo5m,1hou1d, ou uma stringcron. 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 continua pausado mesmo com a chave ativada, e o nó mostra Não será executado. Exemplos são uma regra
cronsem expressão e 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:
| 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.
Acompanhar uma execução sem um endpoint
Você tem outros dois jeitos de saber o resultado de uma execução:
- Consulte periodicamente. Acompanhe a execução com
GET /v1/workflow-executions/:id, ou a tarefa de um único nó comGET /v1/jobs/:id/status. Veja Execuções e Tarefas. - Deixe o workflow avisar você. Termine o workflow com um nó Saída de webhook que envie os resultados para o seu servidor.
Perguntas frequentes
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 tarefa termina?
Sim, depois que você registra um endpoint de webhook com POST /v1/webhook-endpoints. O Nodaro então envia um evento assinado job.completed ou job.failed para a sua URL https sempre que uma das suas tarefas termina, e tenta de novo por cerca de 43 horas.
Como verifico um evento de webhook do Nodaro?
Calcule o HMAC-SHA256 do timestamp, de um ponto e do corpo bruto com o segredo do seu endpoint, e compare com o valor v1 do cabeçalho Nodaro-Signature. Verifique também se o timestamp é recente. O verifyWebhookSignature do SDK faz as duas coisas.
É 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.
Páginas relacionadas
Gatilho de webhook
Gatilho agendado
Saída de webhook
Automações
Execuções
Última atualização
Envio de arquivos
Envie imagens, vídeo e áudio com POST /v1/upload, copie de URLs, importe vídeos de links, corte mídia salva, busque na biblioteca e crie links para arquivos.
Personagens
Crie, atualize, arquive e restaure personagens via REST, gere candidatos a retrato, expressões, ângulos e clipes de movimento e aprove o retrato-âncora.