Webhooks de Entrada

📥 Webhooks de Entrada

Receba eventos de plataformas externas e conceda sementes aos seus clientes automaticamente. Webhooks de entrada permitem que você conecte qualquer ferramenta de terceiros — aplicativos de quiz, formulários, plataformas de avaliação, Zapier, Make e mais — ao seu programa de fidelidade LoyaltyTree.

Como Funciona

O sistema de webhook de entrada utiliza um modelo de Fontes & Códigos:

1. Criar uma Fonte — Uma fonte representa uma plataforma ou ferramenta externa (por exemplo, "Typeform", "Zapier", "Meu Aplicativo de Quiz"). Cada fonte recebe uma URL de webhook exclusiva e uma chave secreta para segurança.
2. Adicionar Códigos à Fonte — Cada código define uma ação específica que concede sementes (por exemplo, "quiz_completed", "form_submitted", "birthday_claimed"). Você define quantas sementes cada código concede, com limites opcionais.
3. Enviar requisições POST — Sua plataforma externa envia uma requisição POST para a URL do webhook com o código e as informações do cliente. O LoyaltyTree encontra ou cria o cliente e concede as sementes automaticamente.

Começando

Passo 1: Criar uma Fonte de Webhook

Navegue até Loja → [Sua Loja] → Integrações → Webhooks de Entrada. Clique em + Adicionar Fonte e dê um nome que descreva a plataforma externa (por exemplo, "Quizzes Typeform" ou "Automação Zapier").

Quando a fonte for criada, você receberá:

• URL do Webhook — O endpoint para o qual sua plataforma externa enviará requisições
• Segredo do Webhook — Uma chave secreta para assinar requisições (recomendado para segurança)

Passo 2: Adicionar Códigos

Cada código representa uma ação específica que você deseja recompensar. Clique em + Adicionar Código na sua fonte para criar um.

Campo	Requerido	Descrição
Código	Sim	O valor exato enviado no payload do webhook (por exemplo, quiz_completed). Isso deve corresponder ao que sua plataforma externa envia.
Nome de Exibição	Sim	Um nome amigável mostrado no painel de administração e no histórico de transações (por exemplo, "Quiz Completo").
Descrição	Não	Uma nota opcional para sua equipe sobre quando esse código é usado.
Quantidade de Sementes	Sim	Quantas sementes conceder cada vez que esse código for acionado. O padrão é 1.
Máx. Sementes/Cliente	Não	O total máximo de sementes que um único cliente pode ganhar com este código. Deixe em branco para ilimitado. Uma vez que um cliente atinge esse limite, chamadas de webhook adicionais para ele retornarão sucesso, mas concederão 0 sementes.
Cooldown (horas)	Não	Horas mínimas entre as recompensas para o mesmo cliente neste código. Previne abusos limitando a frequência com que um cliente pode ganhar sementes. Deixe em branco para sem cooldown.
Habilitado	—	Alternar para habilitar ou desabilitar este código sem excluí-lo. Códigos desabilitados retornam um erro 403.

Códigos & Limites Explicados

Códigos e seus limites trabalham juntos para lhe dar controle preciso sobre como as sementes são concedidas:

Quantidade de Sementes

Cada código tem uma quantidade fixa de sementes. Cada vez que o webhook é acionado com esse código, o cliente recebe exatamente essa quantidade de sementes. Por exemplo, se você definir "quiz_completed" para 5 sementes, cada chamada de webhook qualificada concede 5 sementes.

Máx. Sementes por Cliente

Isso define um limite vitalício por cliente por código. É o total de sementes que o cliente pode ganhar com este código específico, não o número de vezes que ele pode acioná-lo.

Cooldown (Horas)

Define um tempo mínimo de espera entre as recompensas de sementes para o mesmo cliente no mesmo código. O temporizador de cooldown começa a contar a partir da última recompensa bem-sucedida.

Formato da Requisição

Envie uma requisição POST para sua URL de webhook com o seguinte corpo JSON:

{
  "code": "seu_codigo_aqui",
  "customer": {
    "email": "cliente@exemplo.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* Pelo menos um de email ou shopify_customer_id é requerido. O e-mail é requerido quando o cliente não existe ainda no LoyaltyTree.

Verificação de Assinatura HMAC (Recomendado)

Para verificar se as requisições estão realmente vindo da sua plataforma (e não de alguém que encontrou sua URL de webhook), assine suas requisições usando HMAC-SHA256.

Cabeçalhos de assinatura suportados (o LoyaltyTree verifica todos eles):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

O valor da assinatura pode ser o hash hexadecimal cru ou prefixado com sha256= (ambos os formatos são aceitos).

Alternativa: Autenticação de Token Simples

Se a assinatura HMAC não for possível na sua plataforma, você pode passar seu segredo de webhook como um token simples no cabeçalho X-Token. O LoyaltyTree irá compará-lo diretamente ao seu segredo.

Exemplo: Assinando com Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completed',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'seu_segredo_do_webhook')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Exemplo: Assinando com Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completed",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'seu_segredo_do_webhook',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Exemplo: Usando cURL (para testes)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: seu_segredo_do_webhook" \
  -d '{"code":"quiz_completed","customer":{"email":"jane@example.com"}}'

Formato de Resposta

Resposta Bem-Sucedida (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Bem-Sucedido, mas Limitado (200)

Quando um cooldown ou limite máximo de sementes impede a concessão, você ainda recebe uma resposta 200, mas com 0 sementes e uma explicação:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Cooldown ativo. Tente novamente em 18 hora(s)."
}

// ou
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Máximo de sementes (15) já concedidas para este código."
}

Respostas de Erro

Exemplos de Casos de Uso

Conectando com Zapier

Zapier é uma das maneiras mais populares de conectar o LoyaltyTree com centenas de outros aplicativos. Estamos construindo uma integração dedicada do LoyaltyTree na Zapier App Store, que tornará a configuração ainda mais fácil — procure por ela no marketplace do Zapier.

Enquanto isso, você pode usar a ação Webhooks by Zapier para se conectar agora:

Conectando com Make (Integromat)

Você também pode usar o módulo HTTP / Fazer uma requisição do Make para enviar webhooks para o LoyaltyTree. Configure-o da mesma forma que o Zapier — defina a URL, adicione o corpo JSON com code e customer, e inclua seu segredo no cabeçalho X-Token.

Logs de Webhook

Cada chamada de webhook de entrada é registrada e visível na seção Webhooks de Entrada da sua página de Integrações. Os logs mostram:

• Timestamp – Quando o webhook foi recebido
• Fonte – Qual fonte o recebeu
• Status – Sucesso ou falha
• Detalhes – Código usado, sementes concedidas ou mensagem de erro
• Payload – O corpo completo da requisição (criptografado em repouso)

Use os logs para verificar se sua integração está funcionando corretamente e para solucionar quaisquer problemas.

Solução de Problemas

Segurança

• Cada fonte recebe um segredo de webhook único de 64 caracteres, gerado automaticamente e criptografado em repouso
• Segredos podem ser regenerados a qualquer momento nas configurações da fonte (o segredo antigo para de funcionar imediatamente)
• Payloads de requisição são criptografados nos logs para privacidade
• A verificação de assinatura utiliza comparação segura por tempo para prevenir ataques de temporização
• Fontes e códigos podem ser desabilitados individualmente sem excluí-los