Como posso acionar um Fluxo de eventos a partir de um webhook de outro sistema?

Quer integrar suas ferramentas externas e aprender como acionar um Fluxo de eventos a partir de um webhook no Octadesk? Neste artigo, te mostramos o passo a passo completo para conectar sistemas como e-commerces, CRMs ou gateways de pagamento e disparar mensagens e automações no seu atendimento sempre que um evento ocorrer fora da plataforma! 

O que preciso ter antes de começar?

• WhatsApp oficial ativo no Octadesk, com o número que vai enviar as mensagens.

• Um modelo de mensagem de WhatsApp aprovado pela Meta, com variáveis (veja o Passo 3).

• Uma chave de API do Octadesk, gerada em Configurações, Geral, API, de um usuário com permissão para enviar modelos de mensagem. Guarde-a em Tokens externos para usar no bot sem expor o valor.

• Uma loja na Yampi com acesso a Configurações, Webhooks.

• Alguém com acesso ao painel da loja. A configuração do lado da Yampi é feita pela sua empresa; por segurança e em respeito à LGPD, a equipe Octadesk não acessa sistemas de terceiros.

Como o fluxo funciona do início ao fim?

Cliente abandona o carrinho na loja

        ↓

Yampi envia o evento cart.reminder (POST) para o endereço de webhook do Octadesk

        ↓

Fluxo de eventos (tipo Webhooks) executa o bot

        ↓

Formate informações com a IA lê o payload e monta os dados do envio

        ↓

Conecte a outro sistema chama POST /chat/send-template

        ↓

O modelo chega no WhatsApp do cliente; a resposta cai no atendimento

São dois componentes no Octadesk e uma configuração na Yampi, sem ferramentas intermediárias.

Passo 1: como crio o endereço de webhook?

1. No Octadesk, acesse Configurações, Geral, API e abra a aba Webhooks.

2. Clique em Gerar endereço webhook, dê o nome "Yampi - carrinho abandonado" e clique em Gerar e ativar.

3. Nos três pontinhos do endereço, clique em Copiar endereço webhook.

Os detalhes sobre endereços de webhook estão no artigo Como receber eventos de outros sistemas no Octadesk com endereços de webhook?.

Passo 2: como configuro o webhook na Yampi?

1. No painel da Yampi, acesse Configurações, Webhooks e clique em Novo webhook.

2. Dê um nome (por exemplo, "Recuperação de carrinho abandonado Octadesk"), cole a URL do Octadesk no campo URL e mantenha o webhook ativo.

3. Em Eventos, marque apenas Notificação de carrinho abandonado (evento cart.reminder).

4. Em Produtos, deixe vazio para disparar para todos ou selecione produtos específicos.

5. Clique em Salvar.

Como a Yampi se comporta, pelo que observamos nos testes: o evento é enviado cerca de 20 minutos depois de o cliente sair do checkout, tempo definido pela própria Yampi e que não pode ser alterado. O cliente precisa ter preenchido ao menos a etapa de identificação (nome, e-mail, telefone); sem esses dados não há como contatá-lo. Se o mesmo carrinho for atualizado, o evento pode ser enviado de novo.

Passo 3: como crio o modelo de mensagem de WhatsApp?

Mensagens iniciadas pela empresa no WhatsApp precisam de um modelo aprovado pela Meta. Para lembrete de carrinho abandonado, a categoria é Marketing.

Crie as variáveis do modelo no Octadesk antes de criar o modelo. Neste exemplo usamos três: primeiro_nome, resumo_itens e link_carrinho.

Sugestão de texto:

Oi, {{primeiro_nome}}! Você deixou {{resumo_itens}} no carrinho da nossa loja e reservamos pra você.

 

Se quiser retomar de onde parou, é só acessar: {{link_carrinho}}

 

Ficou alguma dúvida sobre o produto, frete ou pagamento? Responda esta mensagem e a gente te ajuda por aqui mesmo.

 

Se não quiser receber mais lembretes, responda SAIR.

O convite para responder não está ali por acaso: é a resposta do cliente que abre a Conversa com o seu time ou com o seu agente de IA.

Envie para aprovação da Meta e aguarde. Anote o ID do modelo, que aparece no Octadesk depois de criado; ele será usado no Passo 5.

Imagem 1: Corpo do modelo de mensagem com as variáveis primeiro_nome, resumo_itens e link_carrinho

Passo 4: como crio o Fluxo de eventos?

1. Acesse Configurações, abra Fluxos de eventos e clique em Criar fluxo de evento.

2. Preencha o Nome do Fluxo (por exemplo, "Carrinho abandonado Yampi - WhatsApp") e uma descrição, como "Recebe o webhook da Yampi, formata os dados com IA e envia modelo de WhatsApp".

3. Em “Fluxo será usado para eventos de”, escolha Webhooks.

4. Em Webhook que irá disparar o fluxo, selecione o endereço criado no Passo 1.

5. Deixe Ativar atraso de execução desmarcado. A Yampi já espera cerca de 20 minutos antes de enviar o evento; se quiser dar ainda mais tempo ao cliente, ative depois.

6. Em Bot que irá executar o fluxo, clique em Criar novo bot, dê um nome e confirme.

7. Clique em Criar. Você será levado à tela Editar o bot do seu fluxo de eventos. Para voltar ao bot depois, use o ícone de lápis ao lado do campo Bot que irá executar o fluxo.

Imagem 2: Tela do fluxo com o tipo Webhooks, o endereço e o bot selecionados

Passo 5: como monto o bot?

O bot terá três blocos ligados em sequência: Início, Formate informações com a IA e Conecte a outro sistema.

Imagem 3: Bot com os blocos Início, Formate informações com a IA e Conecte a outro sistema

5.1 Formate informações com a IA

Arraste o componente para a área de edição, ligue a saída de Início a ele e clique para editar.

• Formato de saída: JSON.

• Instrução de formatação (até 5.000 caracteres): a IA recebe o payload do webhook automaticamente e devolve exatamente o conteúdo que a API de envio espera. Use a instrução abaixo, trocando o número de origem (o seu WhatsApp oficial, no formato +55DDDNUMERO) e o ID do modelo pelos seus. As chaves de variables precisam ter exatamente os mesmos nomes das variáveis usadas no seu modelo.

• Saídas condicionais: deixe desligado neste exemplo, porque todo aviso recebido segue o mesmo caminho.
  

Você recebe o payload JSON do webhook cart.reminder da Yampi (carrinho

abandonado). Monte e retorne SOMENTE o JSON abaixo, válido, sem texto antes

ou depois e sem cercas de código, preenchendo os valores entre <> a partir

do payload:

 

{"origin":{"contact":{"channel":"whatsapp","code":"+55DDDNUMERO"}},

"target":{"contact":{"channel":"whatsapp","code":"<TELEFONE>","name":"<NOME>",

"email":"<EMAIL>"}},"content":{"templateMessage":{"id":"ID_DO_TEMPLATE",

"variables":[{"key":"primeiro_nome","value":"<PRIMEIRO_NOME>"},

{"key":"resumo_itens","value":"<RESUMO_ITENS>"},

{"key":"link_carrinho","value":"<LINK>"}]}},

"options":{"automaticAssign":false}}

 

Regras de preenchimento:

- <TELEFONE>: "+55" seguido dos dígitos de

  resource.customer.data.phone.full_number; se os dígitos já começarem com

  55, use "+" seguido dos dígitos. Exemplo: 11987654321 vira +5511987654321.

- <NOME>: resource.customer.data.name.

- <EMAIL>: resource.customer.data.email; se vazio ou ausente, use os dígitos

  do telefone seguidos de "@octachat.com".

- <PRIMEIRO_NOME>: resource.customer.data.first_name; se vazio, a primeira

  palavra de name; se vazio, "cliente".

- <RESUMO_ITENS>: "o " seguido de resource.items.data[0].sku.data.title; se

  houver mais de um item, acrescente " e mais N item(ns)", com N = total de

  itens menos 1.

- <LINK>: resource.unauth_simulate_url exatamente como veio.

Não altere origin, templateMessage.id, as keys nem options. Não invente valores.

Imagem 4: Formate informações com a IA com Formato de saída JSON e a instrução preenchida

Por que a IA monta o conteúdo inteiro? O payload da Yampi tem dezenas de campos, o telefone vem sem o código do país e a lista de itens tem tamanho variável. A IA resolve essas três coisas com uma instrução em português, sem mapeamento fixo de campos. Se a Yampi mudar o formato, você ajusta a instrução.

5.2 Conecte a outro sistema

Arraste o componente, ligue a saída do bloco de IA a ele e clique para editar.

• Método: POST.

• URL: a URL da API da sua conta, terminando em /chat/send-template. Você encontra a URL base em Configurações, Geral, API.

• Headers: Content-Type com valor application/json, e X-API-KEY com o token salvo em Tokens externos, selecionado pelo botão de token (aparece como $apelido-do-token).

• Body: mantenha Customizar body desligado e a caixa de conteúdo vazia. Assim, o conteúdo enviado é exatamente o JSON que a IA produziu no passo anterior.

• Em caso de falha: ligue esta saída a alguma ação visível, por exemplo um bloco que envie uma notificação para você. Sem isso, uma falha no envio passa despercebida.
  

Clique em Salvar no bot.

Passo 6: como testo a automação?

Há duas formas de testar, e vale fazer as duas.

Teste rápido, sem esperar a Yampi. Copie o payload de um disparo real da Yampi (no histórico do endereço, em Ver payload) ou use um payload de exemplo com a mesma estrutura e envie um POST para a URL do endereço com uma ferramenta como o Postman. O modelo deve chegar ao número informado em full_number em alguns segundos. Use o seu próprio número nos testes.

Teste real. Abra a sua loja em uma janela anônima, coloque um produto no carrinho, avance para o checkout, preencha nome, e-mail e o seu WhatsApp e feche a aba. Acompanhe:

1. Na Yampi, em Vendas, Carrinhos abandonados: o carrinho aparece em alguns segundos.

2. No histórico do endereço de webhook, no Octadesk: o disparo aparece quando a Yampi envia o evento (cerca de 20 minutos, nos nossos testes).

3. No seu WhatsApp: o modelo chega segundos depois.

4. Responda a mensagem: a Conversa aparece no Octadesk como qualquer outra.

Use uma janela anônima nova a cada teste. A Yampi guarda o carrinho em um cookie do checkout; se reaproveitar a janela, você atualiza o carrinho anterior em vez de criar um novo.

O que acontece se o cliente já tiver uma Conversa aberta?

O Fluxo de eventos não verifica se existe Conversa aberta; ele segue a mesma lógica de um envio de modelo pela API:

• Se o modelo sai do mesmo número da sua empresa pelo qual o cliente já conversa, a mensagem entra na Conversa existente.

• Se a sua empresa usa números diferentes para propósitos diferentes (por exemplo, um para Suporte e outro para campanhas), a mensagem sai pelo número escolhido no fluxo e uma nova Conversa é criada nesse contexto.

Escolha o número de origem de acordo com a jornada que você quer desenhar para o cliente.

Como uso os dados do webhook direto no bot?

Além de passar o payload para a IA, você pode usar campos do payload diretamente no Conecte a outro sistema, no corpo, na URL ou nos cabeçalhos, com a sintaxe #{caminho.do.campo}. O caminho segue a estrutura do JSON recebido, com um ponto a cada nível.

Suponha que o endereço de webhook recebeu este payload (uma versão resumida do que a Yampi envia):

{

  "event": "cart.reminder",

  "resource": {

    "id": 638474057,

    "totalizers": { "total_formated": "R$ 19,99" },

    "unauth_simulate_url": "https://minhaloja.pay.yampi.com.br/cart?cart_token=abc123",

    "customer": {

      "data": {

        "first_name": "João",

        "email": "joao@exemplo.com",

        "phone": { "full_number": "11987654321" }

      }

    },

    "items": {

      "data": [

        { "sku": { "data": { "title": "Caderno espiral B5 - 60 páginas" } } },

        { "sku": { "data": { "title": "Caneta gel azul" } } }

      ]

    }

  }

}

Para chegar a um campo, escreva o caminho a partir do início, separando cada nível por ponto. Listas são percorridas pela posição, começando em zero:

O nome do evento

event

#{event}

O primeiro nome do cliente

resource → customer → data → first_name

#{resource.customer.data.first_name}

O telefone

resource → customer → data → phone → full_number

#{resource.customer.data.phone.full_number}

O valor total já formatado

resource → totalizers → total_formated

#{resource.totalizers.total_formated}

O título do primeiro item

resource → items → data → posição 0 → sku → data → title

#{resource.items.data.0.sku.data.title}

O título do segundo item

mesma lista, posição 1

#{resource.items.data.1.sku.data.title}

Um texto fixo junto com um campo

prefixo +55 mais o telefone

+55#{resource.customer.data.phone.full_number}

Um corpo do Conecte a outro sistema usando essa sintaxe ficaria assim:

{

  "cliente": "#{resource.customer.data.first_name}",

  "telefone": "+55#{resource.customer.data.phone.full_number}",

  "produto": "#{resource.items.data.0.sku.data.title}",

  "total": "#{resource.totalizers.total_formated}",

  "link": "#{resource.unauth_simulate_url}"

}

E, com o payload acima, o que seria enviado ao destino:

{

  "cliente": "João",

  "telefone": "+5511987654321",

  "produto": "Caderno espiral B5 - 60 páginas",

  "total": "R$ 19,99",

  "link": "https://minhaloja.pay.yampi.com.br/cart?cart_token=abc123"

}

Isso permite montar o corpo sem IA quando o payload já vem no formato de que você precisa. Neste tutorial preferimos a IA porque a lista de itens tinha tamanho variável e queríamos um resumo legível ("o Caderno espiral B5 e mais 1 item"), algo que um caminho fixo não resolve.

Um ponto de atenção:

• As variáveis oferecidas no seletor do componente (campos de Ticket, de pesquisa ou de Conversa) não têm valor em fluxos disparados por webhook, porque nesse momento não existe Ticket nem Conversa.

O que faço quando algo não funciona?

Nada aparece no histórico do endereço

Painel da Yampi: o carrinho tem dados de identificação? O webhook está ativo e com o evento certo?

A Yampi ainda não enviou, ou o webhook está inativo ou com a URL errada

Disparo com sucesso no histórico, mas nenhuma mensagem chega

Aponte temporariamente o Conecte para um endereço de inspeção (por exemplo, um segundo endereço de webhook do Octadesk ou uma ferramenta como o webhook.site) e dispare de novo. Confira o conteúdo enviado

Conteúdo incompleto (campos vazios), token inválido ou modelo não aprovado

O conteúdo chega com campos faltando

Instrução da IA e caminhos dos campos (resource.customer.data...)

Caminho errado, ou Customizar body ligado com um texto antigo salvo

O Conecte envia um conteúdo diferente do que a IA gera

Campo Body do Conecte

Customizar body está ligado, ou foi desligado sem apagar o texto. Ligue, apague tudo, desligue e salve

A API responde com erro 400 ao enviar o modelo

Códigos das variáveis (primeiro_nome, com underscore), número de origem igual ao do WhatsApp oficial, ID do modelo

Variável com código diferente do cadastrado, modelo não aprovado ou criado em outro número

A mensagem chega várias vezes

Histórico do endereço

O sistema de origem reenviou o evento (a Yampi reenvia quando o carrinho é atualizado). Considere filtrar na origem

Como adapto este tutorial para outros sistemas?

O que muda de um sistema para outro é o payload e a mensagem. O roteiro é o mesmo:

1. Crie o endereço e configure-o no sistema de origem.

2. Dispare um evento de teste e leia o payload no histórico.

3. Escreva a instrução da IA apontando para os campos daquele payload.

4. Use o modelo de mensagem adequado ao caso.

Alguns exemplos: pedido com status atualizado no seu ERP ou plataforma de e-commerce (como a VTEX), tentativa de entrega sem sucesso na sua ferramenta de logística, lead marcado como oportunidade no RD Station Marketing, pagamento pendente em um gateway como o Mercado Pago.

O que significam os termos que aparecem neste tutorial?

1. Webhook: aviso automático que um sistema envia para outro quando algo acontece.

2. Payload: o conteúdo desse aviso, com os dados do acontecimento.

3. Modelo de mensagem (template): mensagem pré-aprovada pela Meta, obrigatória para a empresa iniciar uma Conversa no WhatsApp.

4. Endpoint: o endereço específico da API que executa uma ação, como /chat/send-template para enviar modelos.

5. Token / chave de API: a "senha" que autoriza uma chamada à API. Fica guardada em Tokens externos.

6. Postman: ferramenta gratuita que permite enviar chamadas de teste para uma URL.

Quais são as boas práticas para esta automação?

• Monte com um inspetor. Antes de apontar o Conecte para a API real, aponte para um endereço que mostre o que chegou. Você vê exatamente o conteúdo que o bot enviaria e corrige antes de disparar mensagens de verdade.

• Teste com o seu número. Mensagens de modelo são reais e têm custo.

• Mantenha a saída "Em caso de falha" conectada. É a única forma de perceber uma falha no envio.

• Trate a URL do endereço como senha. Quem tem a URL consegue disparar o fluxo, e o fluxo envia mensagens em nome da sua empresa.

• Filtre na origem. Envie ao Octadesk apenas os eventos que o fluxo vai usar.

• Planeje a continuidade. O envio do modelo é o começo da jornada. Defina para onde vão as respostas: um time dedicado, um bot ou um agente de IA preparado para tirar dúvidas de frete, pagamento e produto.

• Cuide dos dados pessoais. O payload de um carrinho contém nome, telefone, e-mail e, dependendo da plataforma, documento do cliente. Limite quem tem acesso à configuração de webhooks e ao histórico.

Com esse fluxo no ar, cada carrinho abandonado vira uma oportunidade de Conversa, e não mais um número esquecido em uma lista. Seguindo essas práticas, você automatiza com segurança e mantém a integridade dos dados dos seus clientes em cada etapa.