Nó Retorno

O nó Retorno (return_workflow) define o corpo da resposta HTTP quando um workflow é invocado de forma síncrona — tipicamente um trigger Webhook chamado com ?wait=true. Sistemas externos recebem o JSON (ou texto) que você definir em vez de apenas um acknowledgment.

Encontre-o em Lógica em Automações.

Figura 1: Nó Retorno com template JSON de resposta

O que faz

Quando o nó Retorno executa:

1. Se ainda não havia payload de retorno nesta execução, o engine resolve o campo Response / payload (JSON).
2. Faz parse do resultado como JSON quando possível; caso contrário retorna a string bruta.
3. Armazena o valor em context.returnPayload — isso vira o return_payload do workflow no registro de execução.
4. Para chamadas síncronas de webhook, a resposta HTTP ao chamador inclui esses dados (em data na resposta da API).

Se um segundo nó Retorno executar na mesma execução, ele produz { already_set: true } e não sobrescreve o primeiro payload. O primeiro Retorno vence.

Quando o campo body está vazio, o engine recai em context.input (saída do nó anterior) ou context.input.result.

Como configurar

Clique duas vezes no nó Retorno.

Response / payload (JSON)

Template JSON com {{variables}} e referências de nós opcionais:

{
  "success": true,
  "order_id": "{{variables.order_id}}",
  "customer": {
    "name": "{{variables.contact_name}}",
    "phone": "{{variables.contact_phone}}"
  },
  "items_processed": {{loop_1.count}},
  "tier": "{{condition_1.matched_case_id}}"
}

Regras:

• Use estrutura JSON válida — valores string entre aspas; números e booleanos sem aspas ({{loop_1.count}} deve resolver para número para JSON válido).
• Templates dentro de strings são resolvidos antes do parse JSON.
• JSON inválido após resolução pode ser retornado como string simples (fallback de erro de parse).

Saída

Posicionamento no grafo

Coloque Retorno no fim do caminho que você quer que o chamador aguarde. Nós após Retorno ainda podem executar conforme a fiação, mas a resposta síncrona fica fixa no primeiro Retorno.

Para webhooks sem wait=true, a plataforma normalmente responde imediatamente com um ID de execução; Retorno ainda grava return_payload na execução para inspeção posterior.

Dicas e boas práticas

• Um Retorno intencional por caminho. Projete cada ramo para terminar com no máximo um Retorno; evite nós duplicados no mesmo caminho.
• Retorne cedo para erros de validação. Webhook → Condição (payload inválido) → Else → Retorno { "ok": false, "error": "missing phone" } interrompe trabalho relevante e informa o chamador.
• Use Retorno com integrações HTTP. Zapier, n8n e backends customizados costumam precisar de confirmação JSON (IDs criados, flags de status).
• Mantenha payloads pequenos. Arrays grandes em respostas síncronas deixam chamadores lentos; retorne IDs e deixe clientes buscar detalhes em outra API.
• Teste com wait=true. Copie a URL do webhook com ?wait=true, execute o fluxo e inspecione o body da resposta HTTP no cliente ou Postman.
• Combine com nós Variável. Monte {{variables…}} antes para o JSON do Retorno ficar legível.

Exemplos de uso

Exemplo 1 — API de captura de lead (síncrona)

Trigger: Webhook POST /wf/...?...wait=true.

Fluxo:

1. Variável — normalizar name, email, phone
2. Condição — {{variables.email}} is_not_empty
3. Match → CRM Upsert → Retorno

   { "ok": true, "lead_id": "{{crm_1.data.id}}", "message": "Lead created" }
   

4. Else → Retorno

   { "ok": false, "error": "email_required" }
   

O formulário externo recebe JSON imediato de sucesso ou erro de validação.

Exemplo 2 — Endpoint de classificação com IA

Trigger: Webhook — mesa de suporte envia texto do ticket.

Fluxo:

1. OpenAI — classificar ticket
2. JavaScript — parse da saída do modelo para { intent, confidence }
3. Retorno

   {
     "intent": "{{js_1.result.intent}}",
     "confidence": {{js_1.result.confidence}},
     "execution_id": "{{system.execution_id}}"
   }
   

O chamador roteia o ticket sem polling no histórico de execução.

Exemplo 3 — Acknowledgment de webhook de pedido

Trigger: Webhook de pedido Shopify (async fire-and-forget).

Fluxo:

1. Variável — order_id de {{trigger.body.id}}
2. Loop — processamento de line items…
3. Ao concluir → Retorno (para execuções com wait ou para payload registrado)

   { "received": true, "order_id": "{{variables.order_id}}", "lines": {{loop_1.count}} }
   

Mesmo sem wait síncrono, return_payload aparece no histórico de execuções.

FAQ

O que é ?wait=true?

Flag de query na URL do webhook que diz ao WhatsWave para manter a conexão HTTP até o workflow terminar (ou dar timeout) e incluir o payload do Retorno na resposta.

Por que meu chamador recebe body vazio?

Nenhum nó Retorno executou, o body estava vazio e a saída do nó anterior era null, ou a requisição não usou wait síncrono. Verifique return_payload na execução.

Posso retornar HTML em vez de JSON?

O campo espera JSON; uma string resolvida que não seja JSON válido pode retornar como texto bruto conforme o comportamento de parse — JSON é o contrato suportado.

Dois ramos têm Retorno — qual vence?

Só um ramo executa por execução (Condição/Loop), então um Retorno define o payload. Se ambos rodarem em sequência, o primeiro Retorno vence.

Retorno para o workflow?

Não. Ele só define o payload de resposta. Nós downstream ainda executam se conectados — coloque Retorno em arestas terminais quando possível.

Artigos relacionados

• Triggers de Webhook
• Como usar webhooks recebidos
• Nó Variável
• Nó Condição
• Histórico de execuções do workflow