Exemplos: Hotmart, Kiwify, Shopify e formulários

Passo 1: Hotmart: compras e outros eventos

Na Hotmart, em Ferramentas › Ver todas › Webhook (API e notificações), clique em + Cadastrar Webhook, marque os eventos e cole o link da NexTags como URL. Os dados da venda vêm em data, e o nome do evento, em event. Trecho do exemplo oficial da Hotmart (evento de compra, versão 2.0.0), encurtado:

{
  "id": "1234567890123456789",
  "creation_date": 12345678,
  "event": "PURCHASE_APPROVED",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 213344,
      "name": "Product Name"
    },
    "buyer": {
      "email": "buyer@email.com",
      "name": "Buyer Name",
      "first_name": "Buyer",
      "last_name": "Name",
      "checkout_phone": "999999999",
      "checkout_phone_code": "31"
    },
    "purchase": {
      "status": "STARTED",
      "transaction": "HP02316330308193"
    }
  }
}

No exemplo oficial, o telefone vem sem o código do país e sem o DDD, que chega à parte em checkout_phone_code. A Hotmart diz que, nas vendas para fora do Brasil, o código do país vem junto ao telefone. Como a tela do webhook de entrada usa um caminho só para o telefone, confira um envio real no Histórico da Hotmart. Se o número vier incompleto, identifique o contato pelo e-mail e guarde o DDD e o telefone em campos, ou receba o webhook num servidor seu, monte o número completo (55 + DDD + número) e repasse para a NexTags, como no formulário do último passo.

A Hotmart manda em todas as requisições o cabeçalho X-HOTMART-HOTTOK, que identifica a sua conta. A tela do webhook de entrada não tem onde conferir esse cabeçalho: para conferir, receba o webhook num servidor seu. Fonte: Eventos de pedidos do Webhook da Hotmart. A configuração na NexTags, passo a passo: Hotmart.

Passo 2: Kiwify: compra aprovada, Pix e boleto

Na Kiwify, em Apps › Webhooks, crie um webhook, cole o link da NexTags como URL, escolha os produtos e os eventos. Cada evento chega por POST com o JSON no corpo. A Kiwify acrescenta ao link o parâmetro signature, uma assinatura do corpo; a tela do webhook de entrada não tem onde conferir, mas um servidor seu pode. O exemplo oficial da Kiwify, que omite os dados do cliente:

{
  "order_id": "9b1c2d3e-0000-4000-8000-000000000001",
  "order_status": "paid",
  "webhook_event_type": "order_approved"
}

O gatilho que você marca na Kiwify e o valor que chega em webhook_event_type nem sempre têm o mesmo nome:

O carrinho abandonado chega em outro formato, sem webhook_event_type nem order_status: use um webhook de entrada só para ele. A Kiwify espera uma resposta de 200 a 299 em até 40 segundos, tenta de novo quando falha e pode mandar o mesmo evento mais de uma vez. Fonte: Receber e validar webhooks, da Kiwify. A configuração na NexTags, passo a passo: Kiwify.

Passo 3: Shopify: pedidos

No admin da Shopify, em Configurações › Notificações › Webhooks, clique em Criar webhook. Em Evento, escolha o aviso, como Criação de pedido; deixe o Formato em JSON e cole o link da NexTags em URL. O evento não muda depois: crie um webhook para cada aviso, como Pagamento de pedido e Cancelamento de pedido. Trecho do exemplo oficial do tópico orders/create, encurtado:

{
  "id": 820982911946154508,
  "email": "jon@example.com",
  "phone": null,
  "name": "#9999",
  "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg",
  "financial_status": "voided",
  "fulfillment_status": null,
  "total_price": "404.95",
  "billing_address": {
    "name": "Steve Shipper",
    "phone": "555-555-SHIP"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": null
  },
  "line_items": [
    { "title": "Aviator sunglasses", "quantity": 1, "price": "89.99" }
  ]
}

O telefone depende de onde a sua loja pede o número: no endereço de cobrança, no de entrega ($.shipping_address.phone) ou no cliente ($.customer.phone). É um texto livre, digitado pelo cliente, e pode vir vazio: use o e-mail para identificar o contato quando o telefone não for confiável. A Shopify apaga o webhook quando o endereço responde com erro muitas vezes seguidas. Fontes: Criar webhooks, na Central de Ajuda da Shopify e tópicos de webhook da Shopify. A configuração na NexTags, passo a passo: Shopify.

Passo 4: Formulário do seu site

O navegador não deve mandar os dados direto para o link do webhook de entrada: o link ficaria no código da página, à vista de qualquer um. O formulário manda os dados para o seu servidor, e o servidor manda o JSON para a NexTags, com o link guardado na variável de ambiente NEXTAGS_WEBHOOK_URL.

O formulário:

<form method="post" action="/lead">
  <input name="nome" placeholder="Seu nome" required>
  <input name="email" type="email" placeholder="Seu e-mail">
  <input name="telefone" type="tel" placeholder="WhatsApp com DDD" required>
  <button type="submit">Quero falar no WhatsApp</button>
</form>

O servidor, que recebe o formulário, deixa o telefone só com números, com o 55 na frente, e repassa:

// servidor.mjs (Node 18 ou mais novo): node servidor.mjs
import http from 'node:http';

http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/lead') {
    res.writeHead(404).end();
    return;
  }
  let corpo = '';
  for await (const parte of req) corpo += parte;
  const form = new URLSearchParams(corpo);

  const digitos = (form.get('telefone') || '').replace(/\D/g, '');
  const telefone = digitos.length <= 11 ? `55${digitos}` : digitos; // 55 + DDD + número

  const resposta = await fetch(process.env.NEXTAGS_WEBHOOK_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      origem: 'formulario-site',
      lead: {
        nome: form.get('nome') || '',
        email: form.get('email') || '',
        telefone,
      },
    }),
  });
  if (resposta.ok) {
    res.writeHead(303, { Location: '/obrigado.html' }).end();
  } else {
    res.writeHead(502).end('Não deu certo. Tente de novo em alguns minutos.');
  }
}).listen(3000);

# servidor.py (Flask): flask --app servidor run --port 3000
import os
import re

import requests
from flask import Flask, redirect, request

app = Flask(__name__)


@app.post("/lead")
def lead():
    digitos = re.sub(r"\D", "", request.form.get("telefone", ""))
    telefone = "55" + digitos if len(digitos) <= 11 else digitos  # 55 + DDD + número

    resposta = requests.post(
        os.environ["NEXTAGS_WEBHOOK_URL"],
        json={
            "origem": "formulario-site",
            "lead": {
                "nome": request.form.get("nome", ""),
                "email": request.form.get("email", ""),
                "telefone": telefone,
            },
        },
        timeout=30,
    )
    if resposta.ok:
        return redirect("/obrigado.html", code=303)
    return "Não deu certo. Tente de novo em alguns minutos.", 502

<?php
// lead.php: no formulário, use action="/lead.php"
$digitos = preg_replace('/\D/', '', $_POST['telefone'] ?? '');
$telefone = strlen($digitos) <= 11 ? '55' . $digitos : $digitos; // 55 + DDD + número

$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([
        'origem' => 'formulario-site',
        'lead' => [
            'nome' => $_POST['nome'] ?? '',
            'email' => $_POST['email'] ?? '',
            'telefone' => $telefone,
        ],
    ]),
    CURLOPT_TIMEOUT => 30,
]);
curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($codigo >= 200 && $codigo < 300) {
    header('Location: /obrigado.html', true, 303);
} else {
    http_response_code(502);
    echo 'Não deu certo. Tente de novo em alguns minutos.';
}

No formulário, peça a permissão para mandar mensagens pelo WhatsApp, com um texto claro ao lado do botão. Veja Permissão para mensagens (opt-in) e descadastro.