Integre o checkout com qualquer sistema

Como funciona

Você cadastra uma URL (endpoint) no painel e escolhe quais eventos quer receber. Quando algo acontece com um pedido, fazemos um POST em JSON, assinado, para essa URL. É idempotente (não duplica) e tem retentativa automática em caso de falha.

1. Cadastre seu endpoint

No painel, acesse Webhooks, adicione a URL https:// de destino, selecione os eventos e copie a chave secreta gerada — ela valida que a chamada veio da HomePlay. Você pode enviar um evento de teste (com dados fictícios) para configurar o mapeamento sem precisar de uma venda real.

2. Eventos disponíveis

• order.paid Pagamento confirmado — normalmente o gatilho para liberar o acesso/produto.
• order.delivered Pedido entregue (produto digital) / acesso provisionado.
• order.refunded Pagamento estornado — revogue o acesso.
• order.chargeback Chargeback/contestação aberta.
• order.canceled Venda cancelada.
• order.expired Pagamento (Pix) expirado sem pagamento.
• order.failed Pagamento não autorizado.

3. A requisição

Método POST, corpo em JSON. Cada envio inclui os cabeçalhos:

• X-HomePlay-Event — o tipo do evento (ex.: order.paid).
• X-HomePlay-Delivery — id único da entrega.
• X-HomePlay-Signature — sha256=<hmac> do corpo, para validação forte.
• X-HomePlay-Token — a própria chave secreta, para validação simples (ideal p/ no-code).

4. Validação (segurança)

Escolha uma das formas para garantir que a chamada é legítima:

Opção A — Token (simples, ideal para Bubble/no-code)

Compare o cabeçalho X-HomePlay-Token com a sua chave secreta. Se for igual, prossiga; senão, ignore.

Opção B — Assinatura HMAC (validação forte)

Calcule o HMAC-SHA256 do corpo cru da requisição usando a chave secreta e compare com o valor de X-HomePlay-Signature (após o sha256=).

5. Exemplo de payload

Evento order.paid (os demais eventos seguem a mesma estrutura, mudando o event e o status):

{
  "event": "order.paid",
  "id": "a1b2c3d4e5f6...",
  "createdAt": "2026-09-10T14:32:00.000Z",
  "company": { "slug": "sua-loja", "name": "Sua Loja" },
  "order": {
    "ref": "EC-9K2M4X",
    "status": "paid",
    "paymentMethod": "credit",
    "amountCents": 8990,
    "currency": "BRL",
    "quantity": 1,
    "tokenReference": "ref-do-seu-sistema"
  },
  "customer": {
    "name": "Ana Beatriz Souza",
    "email": "ana@email.com",
    "doc": "12345678909",
    "personType": "f",
    "cellNumber": "(11) 98888-0000",
    "marketingConsent": true
  },
  "product": { "sku": "PLANO-PREMIUM", "name": "Plano Premium", "credits": 1 },
  "attribution": {
    "channel": "google_ads",
    "source": "google",
    "medium": "cpc",
    "campaign": "sua-campanha",
    "term": "sua-palavra-chave",
    "content": "seu-anuncio",
    "gclid": "EXEMPLO_gclid_123",
    "fbclid": null,
    "referrer": "google.com",
    "landing": "seguro.sualoja.com.br/"
  },
  "matching": {
    "eventId": "EC-9K2M4X",
    "emailSha256": "b1c2...(sha-256 do e-mail)",
    "phoneSha256": "a9b8...(sha-256 do telefone)"
  }
}

Rastreio de origem (atribuição)

Quando disponível, cada pedido traz um objeto attribution com a origem da venda — útil para medir de onde vêm suas conversões. O campo channel já vem classificado (ex.: google_ads, meta_ads, paid, email, whatsapp, ai_assistant, organic_search, organic_social, referral, direct), e os parâmetros crus (utm_*, gclid, fbclid, referrer) vêm junto para o seu próprio cruzamento.

É um campo opcional e informativo: pode vir com valores null (compra direta ou origem não detectada) e não deve ser usado como validação de segurança. Para máxima captação, faça o link do seu site para o checkout preservar os parâmetros de campanha (utm_*/gclid) na URL.

Quando o checkout está em outro domínio (repasse de parâmetros)

Se o anúncio cai primeiro no seu site e só depois o cliente vai para o checkout (em outro domínio), os parâmetros de campanha precisam viajar no link — senão a origem se perde. Cadastre os domínios do seu site no painel (Empresa → Rastreio de origem) para que suas próprias visitas não contem como "Referência", e adicione este trecho ao seu site para repassar os parâmetros ao checkout:

<script>
(function () {
  // Repassa os parâmetros de campanha do seu site para o link do checkout.
  var KEEP = /^(utm_|gclid$|gbraid$|wbraid$|fbclid$|ttclid$|msclkid$)/i;
  var CHECKOUT = 'seguro.sualoja.com.br'; // <- troque pelo host do SEU checkout
  var carry = [];
  new URLSearchParams(location.search).forEach(function (v, k) {
    if (KEEP.test(k)) carry.push(encodeURIComponent(k) + '=' + encodeURIComponent(v));
  });
  if (!carry.length) return;
  document.querySelectorAll('a[href]').forEach(function (a) {
    if (a.href.indexOf(CHECKOUT) === -1) return;
    a.href += (a.href.indexOf('?') === -1 ? '?' : '&') + carry.join('&');
  });
})();
</script>

APIs de conversão (Google/Meta) — bloco matching

Para devolver a venda ao Google/Meta (Enhanced Conversions / Conversions API) sem trafegar dado pessoal em claro, cada pedido traz um bloco matching: o eventId (use como event_id para deduplicar o evento do navegador com o do servidor); emailSha256 (hash SHA-256 do e-mail, serve Meta e Google); e phoneSha256 (hash do telefone no formato Meta CAPI — dígitos com DDI, sem "+"; para o Google Enhanced Conversions o telefone precisa do "+"). Os hashes só são enviados quando há customer.marketingConsent.

6. Boas práticas

• Libere o acesso/credite somente no order.paid; revogue no order.refunded e order.chargeback.
• Responda com 2xx rapidamente. Em caso de erro, reenviamos automaticamente com espera progressiva.
• Use o campo id (ou order.ref) para não processar o mesmo evento duas vezes (idempotência).

Integrações prontas

• Bubble — receba no Backend Workflow API e valide pelo X-HomePlay-Token.
• Zapier / Make — use um gatilho de webhook e mapeie os campos do payload.
• ERP / sistema próprio — um endpoint HTTP que recebe o JSON e executa sua regra de negócio.

API

Além dos webhooks (push), uma API REST para consultar pedidos por chave de acesso está em evolução. Precisa de um recurso específico? Fale com a gente pelo suporte.