# Webhook de entrada: receber dados de outro sistema

> Mande um JSON de outro sistema para o link de um webhook de entrada. O formato, o contato achado pelo telefone ou e-mail, o JSONPath aceito e um teste em cURL.

Endereço: https://docs.nextags.com.br/webhooks/webhook-de-entrada/
Tipo: Guia

Atualizado em: 26/10/2026

O webhook de entrada é um link da sua conta que recebe dados de outro sistema, como uma loja, uma plataforma de cursos ou o formulário do seu site. A cada envio, a NexTags acha o contato pelo telefone ou pelo e-mail (ou cria um novo), salva os valores recebidos nos campos do contato e inicia o fluxo escolhido. Este guia mostra o lado de quem envia: o formato do JSON, os caminhos aceitos pela tela e um teste com código. A configuração da tela, passo a passo, está em [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/).

**Antes de começar**

- Um webhook de entrada criado em **Ferramentas** › **Webhooks de entrada**. Veja [Webhooks de entrada: receber dados de outro sistema](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/).
- Os campos personalizados que vão guardar os dados. Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/).
- O fluxo que roda depois, publicado. Se ele manda WhatsApp para quem não falou com você nas últimas 24 horas, precisa começar com um Modelo de Mensagem aprovado: veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/).
- Um exemplo do JSON que o outro sistema vai mandar.

## Passo a passo

### 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.

**Guardar o link numa variável de ambiente**

```bash
# macOS e Linux
export NEXTAGS_WEBHOOK_URL="SEU_LINK_DO_WEBHOOK"
```
```powershell
# 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](https://docs.nextags.com.br/webhooks/seguranca-e-testes/).

### 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](https://help.nextags.com.br/tutoriais/contatos/formato-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:

```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"
  }
}
```

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:

| Campo da tela | JSONPath | Valor no exemplo |
|---|---|---|
| **Número de telefone** | `$.cliente.telefone` | `5511988776655` |
| **Endereço de e-mail** | `$.cliente.email` | `ana@exemplo.com.br` |
| **Nome completo** (opcional) | `$.cliente.nome` | `Ana Souza` |

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

| **Campo Personalizado** | **JSONPath** | Valor no exemplo |
|---|---|---|
| ID do pedido (texto) | `$.pedido.id` | `PED-1001` |
| Valor do pedido (número) | `$.pedido.total` | `249.9` |
| Produto (texto) | `$.pedido.itens[0].produto` | `Curso de Confeitaria` |
| Origem (texto) | `$["dados-extras"]["origem"]` | `site` |

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:

| Forma | Quando usar | Exemplo |
|---|---|---|
| `.chave` | Chave com letras sem acento, números e `_`, que não começa com número | `$.cliente.email` |
| `["chave"]` | Qualquer outra chave: com hífen, espaço, acento ou começando com número. Aspas simples também valem | `$["dados-extras"]["origem"]` |
| `[n]` | Um item de lista, contando do zero | `$.pedido.itens[0].produto` |

```jsonpath
$.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](https://docs.nextags.com.br/webhooks/mapear-campos/).

### 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.

```text
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.

**Enviar um JSON de teste para o webhook de entrada**

```bash
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" }
  }'
```
```javascript
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());
```
```python
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
<?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.

## Pronto: como conferir

- O contato aparece em **Contatos**, com os campos preenchidos. Pela API, procure pelo e-mail com [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/).
- O fluxo chegou ao telefone do teste. No painel do contato, na **Caixa de Entrada**, ele aparece em **Histórico** › **Fluxos/Passos Executados**.
- Um segundo envio com o mesmo telefone ou e-mail atualiza o mesmo contato, sem criar outro.

## Se não funcionou

### O teste devolveu um código de 400 em diante

Confira se o link está inteiro, se o JSON é válido e se o cabeçalho `Content-Type: application/json` foi enviado. Anote o código e o corpo da resposta: eles ajudam o suporte a achar a causa.

### O envio foi aceito, mas nada aconteceu

Confira se o webhook está **Ativo**, se o link é o deste webhook e se o caminho do telefone ou do e-mail acha o valor no JSON que você mandou. Confira também se o fluxo está publicado. Veja [Meu webhook de entrada não recebe os dados](https://help.nextags.com.br/perguntas/integracoes/webhook-nao-recebe/).

### O contato chegou, mas um campo ficou vazio

O caminho daquele campo não achou o valor. Cole em **Sample JSON** um envio real, clique em **Load sample JSON** e confira o `Result:` de cada caminho em **Save incoming data**. Confira também o tipo do campo: um valor com letras não cabe num campo de número.

### O caminho mostra um aviso em inglês

`Start the path with $.` pede o `$` no começo. `Use .key, ["key"], or [0]. Filters and wildcards are not supported.` quer dizer que a forma do caminho não é aceita. `Select a value rather than an object or array.` pede um valor, e não um grupo de dados. `No value found in sample data.` diz que o exemplo não tem esse caminho: se o dado é opcional, dá para salvar assim. A lista completa está em [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/).

### O exemplo não carrega

`Use sample JSON smaller than 1 MB.` pede um exemplo menor. `Sample JSON is too large or deeply nested. Use a smaller sample.` aparece com mais de 10 mil itens ou mais de 60 níveis: corte as listas longas do exemplo, deixando só o primeiro item.

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Vou mandar dados do meu sistema para um webhook de entrada da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/webhook-de-entrada.md

Este é um exemplo do JSON que o meu sistema envia, sem dados reais: [cole aqui]. Me diga os caminhos (JSONPath só com .chave, ["chave"] e [0]) do telefone, do e-mail e do nome, os campos personalizados que devo criar, com o tipo de cada um, e escreva em [sua linguagem] o código que manda esse JSON por POST para o link guardado na variável de ambiente NEXTAGS_WEBHOOK_URL.
```