Webhook de entrada: receber dados de outro sistema

Passo 1: Copie o link e guarde fora do código

O link fica no ícone Obter Link, no topo do editor do webhook, ou no menu da linha, na lista Webhooks de entrada. A tela não mostra o link: o clique copia. Cole o link inteiro, como veio, no outro sistema. Cada webhook tem o seu link.

O link não pede chave de API. Quem tem o link consegue criar contatos e iniciar o fluxo, então trate o link como uma senha: nos seus scripts, guarde numa variável de ambiente.

# macOS e Linux
export NEXTAGS_WEBHOOK_URL="SEU_LINK_DO_WEBHOOK"

# Windows (PowerShell)
$env:NEXTAGS_WEBHOOK_URL = "SEU_LINK_DO_WEBHOOK"

Troque SEU_LINK_DO_WEBHOOK pelo link copiado. Se o link vazar, veja como trocar.

Passo 2: Monte o JSON

O corpo é um objeto JSON. Ele precisa trazer o telefone ou o e-mail do contato, no caminho que você vai configurar na tela. Basta um dos dois: com ele, a NexTags acha o contato ou cria um novo.

• Telefone: mande só números, com o código do país e o DDD, como 5511988776655. Veja O formato certo do telefone.
• E-mail: o endereço completo, como ana@exemplo.com.br.
• Outros dados: qualquer chave, em qualquer nível. Cada dado que você quiser guardar ganha um caminho na tela.

O exemplo deste guia, um pedido pago:

{
  "evento": "pedido_pago",
  "cliente": {
    "nome": "Ana Souza",
    "email": "ana@exemplo.com.br",
    "telefone": "5511988776655"
  },
  "pedido": {
    "id": "PED-1001",
    "total": 249.9,
    "itens": [
      { "produto": "Curso de Confeitaria", "quantidade": 1 }
    ]
  },
  "dados-extras": {
    "origem": "site"
  }
}

Cole esse exemplo em Sample JSON, no editor do webhook, e clique em Load sample JSON. O exemplo serve para montar e conferir os caminhos: ele não cria contato nem inicia fluxo. O limite é de 1 MB.

Passo 3: Escreva os caminhos (JSONPath)

Em Find or create contact, diga onde estão o telefone e o e-mail do contato. Para o JSON do exemplo:

Em Save incoming data, ligue cada valor a um campo, com + Adicionar associação de campo para cada novo valor:

A lista de Save incoming data também tem Endereço de e-mail, Número de telefone, Nome, Sobrenome e Nome completo, além dos campos personalizados. Embaixo de cada caminho, a tela mostra Result: com o valor achado no exemplo.

A tela aceita só três formas de caminho, sempre começando com $, o JSON inteiro:

$.cliente.telefone
$["dados-extras"]["origem"]
$.pedido.itens[0].produto

Filtros, curingas (*), dois pontos seguidos (..) e índices negativos não funcionam. O caminho precisa chegar num valor (um texto, um número, true ou false), e não num objeto ou numa lista inteira. Mais exemplos e o tipo de campo certo para cada valor estão em Mapear o corpo recebido para campos do contato.

Passo 4: Escolha o fluxo e salve

Em Após salvar os dados, escolha o fluxo em Enviar Fluxo. Ele começa depois que os campos do contato são salvos, então já pode usar os valores recebidos, como {{ID do pedido}} numa mensagem. Clique em Salvar, no topo do editor, e confira na lista se o interruptor Ativo está ligado.

Ao salvar, a tela exige o caminho do telefone ou do e-mail, pelo menos uma associação em Save incoming data e o fluxo. Ela confere os caminhos de Find or create contact, mas não os de Save incoming data: antes de salvar, olhe o Result: de cada um. Uma linha sem campo ou sem caminho é descartada ao salvar.

Find or create contact: $.cliente.telefone e $.cliente.email
Save incoming data:     $.pedido.id → ID do pedido
Após salvar os dados:   Enviar Fluxo → Pedido pago

Passo 5: Envie um teste

Mande o JSON para o link com um POST, com o JSON no corpo e o cabeçalho Content-Type: application/json, o formato das plataformas que enviam webhooks. Use o seu próprio telefone ou e-mail no lugar dos dados de exemplo, para receber o fluxo.

curl -X POST "$NEXTAGS_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "evento": "pedido_pago",
    "cliente": {
      "nome": "Ana Souza",
      "email": "ana@exemplo.com.br",
      "telefone": "5511988776655"
    },
    "pedido": {
      "id": "PED-1001",
      "total": 249.9,
      "itens": [{ "produto": "Curso de Confeitaria", "quantidade": 1 }]
    },
    "dados-extras": { "origem": "site" }
  }'

const resposta = await fetch(process.env.NEXTAGS_WEBHOOK_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    evento: 'pedido_pago',
    cliente: {
      nome: 'Ana Souza',
      email: 'ana@exemplo.com.br',
      telefone: '5511988776655',
    },
    pedido: {
      id: 'PED-1001',
      total: 249.9,
      itens: [{ produto: 'Curso de Confeitaria', quantidade: 1 }],
    },
    'dados-extras': { origem: 'site' },
  }),
});
console.log(resposta.status, await resposta.text());

import os

import requests

resposta = requests.post(
    os.environ["NEXTAGS_WEBHOOK_URL"],
    json={
        "evento": "pedido_pago",
        "cliente": {
            "nome": "Ana Souza",
            "email": "ana@exemplo.com.br",
            "telefone": "5511988776655",
        },
        "pedido": {
            "id": "PED-1001",
            "total": 249.9,
            "itens": [{"produto": "Curso de Confeitaria", "quantidade": 1}],
        },
        "dados-extras": {"origem": "site"},
    },
    timeout=30,
)
print(resposta.status_code, resposta.text)

<?php
$ch = curl_init(getenv('NEXTAGS_WEBHOOK_URL'));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'evento' => 'pedido_pago',
        'cliente' => [
            'nome' => 'Ana Souza',
            'email' => 'ana@exemplo.com.br',
            'telefone' => '5511988776655',
        ],
        'pedido' => [
            'id' => 'PED-1001',
            'total' => 249.9,
            'itens' => [['produto' => 'Curso de Confeitaria', 'quantidade' => 1]],
        ],
        'dados-extras' => ['origem' => 'site'],
    ]),
    CURLOPT_TIMEOUT => 30,
]);
$corpo = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $corpo, PHP_EOL;

Os exemplos mostram o código HTTP e o corpo da resposta. O formato da resposta do link não está documentado: anote o que voltou no seu teste. Um código de 200 a 299 indica que o envio foi aceito.