Iniciar um fluxo por webhook

O gatilho Webhook dá a um fluxo uma URL própria. Qualquer plataforma que saiba mandar um webhook — a sua loja, um formulário, um CRM, uma plataforma de cursos — chama essa URL com os dados dela, no formato dela, e o fluxo começa. Cada campo do que chegou pode ser usado nas mensagens, nos templates, nas condições e nos campos do contato.

A diferença para o gatilho API: lá o seu sistema chama o Joinotify com uma chave e no formato do Joinotify. Aqui não há chave nem formato a seguir — você cola uma URL num campo de configuração da plataforma e escolhe no editor de onde vem cada dado.

Preparar o fluxo

1. No editor, adicione um gatilho e escolha Webhook. A URL aparece na hora, antes de publicar — é ela que você cola na plataforma.
2. Em Plataforma, escolha WordPress / WooCommerce ou Qualquer plataforma.
3. Clique em Aguardar evento e mande um teste pela plataforma (ou cole um exemplo em Colar JSON). O que chegar vira uma árvore: a partir daí você escolhe os campos clicando, em vez de digitar caminhos.
4. Em Contato, diga onde está o telefone — e, se quiser, o nome e o e-mail.
5. Ligue o gatilho ao primeiro passo, publique e ative o fluxo.

A URL tem a forma https://api.joinotify.com/hooks/whk_… e é a senha do gatilho: quem tiver a URL consegue iniciar o fluxo. Se ela vazar, Gerar nova URL troca o endereço — com a opção de deixar o antigo funcionando por 24 horas, para dar tempo de colar o novo.

WooCommerce

1. No WordPress, abra WooCommerce → Configurações → Avançado → Webhooks e clique em Adicionar webhook.
2. Status: Ativo. Tópico: Pedido criado — ou Pedido atualizado, para acompanhar pagamento e envio.
3. URL de entrega: a URL do gatilho.
4. Segredo: no gatilho, clique em Ativar a assinatura do WooCommerce e cole aqui o segredo gerado.
5. Salve. Com Aguardar evento ligado, faça um pedido de teste na loja para capturar um exemplo.

Com a plataforma WooCommerce escolhida, sem você indicar nada, o contato vem do bloco de cobrança do pedido: billing.phone, billing.first_name, billing.last_name e billing.email. Um telefone sem código do país, como (11) 98765-4321, é lido como do país escolhido no gatilho (Brasil, por padrão).

O teste que o WooCommerce manda ao salvar o webhook (webhook_id=…) é respondido sem virar evento.

Um webhook, vários momentos

O tópico Pedido atualizado dispara a cada mudança do pedido. Use o Filtro do gatilho para começar só no que interessa — status igual a processing, por exemplo — e deixe o mesmo pedido com o mesmo status contar uma vez só (é o padrão, veja Eventos repetidos).

O que a plataforma pode mandar

• JSON (application/json) — um objeto; uma lista chega como items.
• Formulário (application/x-www-form-urlencoded), inclusive campos aninhados do jeito do PHP: cliente[telefone]=… vira cliente.telefone.
• Texto, que chega como text.
• A query string da URL fica em $query, e os cabeçalhos da plataforma (como X-WC-Webhook-Topic) em $headers — nunca os que autenticam.

O corpo vai até 256 kB. POST, PUT e PATCH são aceitos; um GET na URL responde 200, para as plataformas que testam o endereço antes de salvar.

Assinatura

Além da URL, a plataforma pode provar que foi ela quem mandou. No gatilho, em Assinatura:

Tipo	O que o Joinotify confere
Só a URL	Nada além do endereço (padrão)
WooCommerce	X-WC-Webhook-Signature: HMAC-SHA256 do corpo, em Base64, com o segredo do webhook
HMAC-SHA256	O cabeçalho que você escolher, em hex ou Base64, com prefixo opcional (sha256=)
Cabeçalho fixo	O cabeçalho que você escolher tem exatamente o valor combinado

A assinatura é conferida sobre os bytes que chegaram, antes de o corpo ser lido. Uma chamada com a assinatura errada recebe 401 e não vira evento.

Respostas

A plataforma só recebe erro quando a chamada está errada:

Status	Quando
202	O evento foi aceito — { "ok": true, "event_id": "…" }
404	A URL não existe (ou foi trocada e o prazo da antiga acabou)
401	A assinatura não confere
400	O JSON não é válido
413	O corpo passa de 256 kB
415	Um formato que o Joinotify não lê (multipart/form-data)
429	Chamadas demais — até 20 por segundo por URL e 60 por conta

Todo o resto — fluxo pausado, conta sem acesso, pedido sem telefone, evento repetido — é 202 e fica registrado em Eventos recebidos. É de propósito: uma plataforma que recebe erro tenta de novo e, depois de algumas falhas, desativa o webhook, e ninguém fica sabendo por quê.

Eventos recebidos

No editor, Eventos recebidos lista cada chamada e o que aconteceu com ela:

Situação	O que quer dizer
Iniciou o fluxo	Uma execução começou para o contato
Filtrado	O evento não passou no filtro do gatilho
Repetido	O mesmo evento já tinha chegado
Sem telefone	Nenhum telefone válido no caminho escolhido
Contato desconhecido	O gatilho está para não criar contatos, e o telefone não é de nenhum
Fluxo inativo	O fluxo está em rascunho ou pausado
Gatilho não publicado	A versão publicada não tem este gatilho
Gatilho sem próxima etapa	O contato foi atualizado, mas nada foi enviado
Dentro do intervalo	Chegou dentro do intervalo mínimo por contato
Entregue a quem esperava	Uma execução em Aguardar evento seguiu com ele
Conta bloqueada	A conta está sem acesso ao envio

O detalhe de cada evento mostra os dados (com CPF, CNPJ e cartões mascarados até você pedir), os cabeçalhos e a execução que ele iniciou, e tem Rodar de novo. Os dados de um evento ficam guardados por 30 dias, ou pelo prazo de retenção de mensagens do seu plano, se for menor. Depois disso só a situação continua no registro. Na lista de fluxos, um fluxo cujo webhook teve três ou mais eventos sem resultado nas últimas 24 horas mostra um aviso.

Eventos repetidos

Opção	Conta como o mesmo evento
Automático — WooCommerce	O mesmo pedido com o mesmo status, por 30 dias: editar o pedido não confirma de novo
Automático — outras	Um cabeçalho de idempotência (Idempotency-Key, X-Webhook-Id, X-Event-Id, X-Delivery-Id), por 24 horas; sem ele, o mesmo corpo em até 5 minutos
Por um campo	O mesmo valor no campo escolhido, por 24 horas
Por um cabeçalho	O mesmo valor no cabeçalho escolhido, por 24 horas
Nunca	Todo evento inicia o fluxo

Um evento filtrado não conta como visto: o próximo, que passe no filtro, inicia normalmente.

Com as outras automações do contato

Por padrão, uma execução iniciada por webhook roda junto com o que o contato já tem em andamento: um pedido não interrompe a pesquisa ou o atendimento automático que a pessoa está respondendo. Quando o contato escreve, a resposta vai para a execução que está esperando texto — uma pergunta, um Aguardar resposta —, não para um template esperando um toque de botão.

No gatilho você pode trocar para Substituir só a anterior deste fluxo ou Substituir qualquer automação em andamento (como os gatilhos de conversa), e definir um intervalo mínimo por contato.

Guardar no contato e linha do tempo

• Guardar no contato copia campos do evento para os campos do contato antes de o fluxo começar — o valor do último pedido, o CPF, a data da compra. Eles servem depois para segmentar campanhas e em outros fluxos. O nome e o e-mail que a plataforma manda só preenchem o que estiver vazio.
• Linha do tempo escreve uma linha no histórico do contato, que a equipe vê na caixa de entrada: Pedido {{trigger.number}} — {{trigger.total:money}}.

Esperar outro evento

O passo Aguardar evento para uma execução até um gatilho webhook — deste fluxo ou de outro — receber um evento com o mesmo valor num campo. É o que faz uma recuperação de carrinho parar quando o pedido é pago:

1. Um fluxo começa no evento de carrinho abandonado e manda o primeiro lembrete.
2. Aguardar evento: o gatilho do pedido pago, o valor {{trigger.cart_token}} desta execução, o caminho cart_token no evento esperado, até 1 dia.
3. Pela saída Chegou, agradeça; pela saída Não chegou, mande o segundo lembrete.

O evento que chegou fica em {{flow.<nome>.…}}, se você der um nome a ele no passo.

Testar

Testar, no editor, pode levar o exemplo capturado: a execução começa pelo gatilho webhook no seu WhatsApp, com as variáveis preenchidas como estariam para o cliente.

Próximo: Variáveis e dados nos fluxos.