Node comunitário StackZap para n8n: instalação e uso

Como o n8n conversa com a StackZap

O n8n documenta o HTTP Request como um nó para fazer chamadas a serviços com API REST. Para uma operação de saída, o fluxo envia método, URL, autenticação e corpo JSON. Para receber uma notificação, um Webhook node do n8n oferece uma URL receptora; a configuração da StackZap deve apontar para o endpoint correto e usar os eventos e segredos disponíveis para sua versão.

O pacote comunitário oferece um node de ação chamado StackZap com operações para instâncias, mensagens, grupos, contatos, webhooks, integrações Chatwoot, agendamentos, chamadas, diagnósticos e outros recursos descritos no README do pacote. Os endpoints são executados conforme a operação escolhida; confira a versão instalada e a documentação da API.

Por ser um node comunitário separado, ele não é mantido como node embutido pelo n8n. A instalação permite executar código de terceiros na sua instância: revise o pacote, as permissões e o processo de atualização de acordo com a política da sua equipe.

Instale o pacote comunitário

1. No n8n, abra Settings → Community Nodes → Install, se essa opção estiver disponível para seu tipo de instalação e usuário administrador.
2. Procure ou informe o pacote n8n-nodes-stackzap e selecione a versão desejada. A versão publicada consultada para este guia é 0.1.1; confirme a tag atual antes de instalar.
3. Leia os avisos de risco do n8n para pacotes comunitários e só instale código que sua organização aprovou.
4. Crie uma credencial API StackZap. O pacote pede a URL base sem /v1 e sem barra final, mais a chave enviada no header X-API-Key.
5. Escolha o recurso e a operação; parâmetros de caminho e consulta aparecem conforme a operação. Teste em um ambiente controlado.

O acesso de instalação pode depender da modalidade do n8n, das permissões de administrador e das políticas da instância. Consulte a documentação oficial de instalação de community nodes. Confira o pacote no npm e seus arquivos publicados antes de ativá-lo.

Alternativa: envie texto pelo HTTP Request

Use esse caminho se não quiser instalar o pacote comunitário ou se a operação desejada ainda não estiver modelada no node.

1. Crie uma credencial de cabeçalho para a API, com o nome X-API-Key e a chave do ambiente. Restrinja quem pode usar e visualizar a credencial.
2. Adicione um nó HTTP Request e escolha o método POST.
3. Informe a URL no formato https://URL-DO-SEU-AMBIENTE/v1/instances/ID-DA-INSTANCIA/messages/text. Troque host e ID pelos valores do painel.
4. Selecione autenticação usando a credencial de cabeçalho, envie corpo JSON e mapeie os dados necessários do nó anterior.
5. Execute uma vez com destinatário de teste autorizado, examine o status e a resposta e só então conecte o nó ao evento definitivo.

O contrato documentado requer os campos to e text; to é o JID do destinatário. Exemplo de corpo para o campo JSON do nó, usando expressões do n8n:

{
  "to": "{{$json.destinatario_jid}}",
  "text": "{{$json.mensagem}}"
}

Não copie uma chave real para um workflow exportado, issue ou captura de tela. Separe credenciais de teste e produção, valide campos antes de enviar e evite reexecutar às cegas um fluxo que terminou com timeout: a resposta pode ter se perdido depois de a solicitação ser aceita.

Receba eventos com o Webhook node do n8n

O node comunitário StackZap é um node de ação, não um trigger de entrada do n8n. Para receber uma chamada de webhook, use o Webhook node nativo do n8n, que gera a URL receptora. O pacote comunitário também fornece operações para criar, consultar, testar e administrar webhooks pela API.

1. Crie um workflow com um Webhook node e copie a URL de produção somente depois de publicar/ativar o workflow conforme seu ambiente n8n.
2. Configure a URL de callback e os eventos desejados nas opções de webhook da StackZap, usando a documentação da versão atual.
3. Faça um evento de teste e confirme que o n8n recebeu o método, os cabeçalhos e o corpo esperados.
4. Valide a assinatura HMAC conforme a referência técnica antes de executar ações de negócio. Se sua montagem do n8n não permitir validar os bytes originais necessários, use um receptor intermediário que faça essa verificação.
5. Persista ou encaminhe o evento de modo idempotente; trate repetição, erro e indisponibilidade do fluxo receptor.

Uma URL pública com HTTPS pode ser necessária para que o serviço que envia o webhook alcance o n8n. Para instalações atrás de firewall, redes privadas ou ambientes locais, planeje uma rota segura e documentada. Não desative a validação da assinatura para contornar erro.

Veja o guia de recebimento de webhooks StackZap, o artigo sobre validação HMAC e o manual do HTTP Request no n8n.

Cuidados para fluxos confiáveis