Os Webhooks permitem à Loyaltify avisar de imediato os seus outros sistemas quando algo acontece, como a adesão de um novo cliente ou um cliente a ganhar pontos. A Loyaltify envia uma mensagem curta para um endereço à sua escolha, e o seu sistema pode agir com base nela.

São úteis para manter um CRM atualizado, acionar e-mails nas suas próprias ferramentas ou criar relatórios. Este guia explica como configurar um webhook, o que contém cada mensagem e como verificar se as mensagens estão a chegar.

💡 Convém saber: Esta funcionalidade faz parte do plano Advanced. Deixa de funcionar se mudar para um plano inferior.

Configurar um webhook

Passo 1: Abra a configuração do webhook

Aceda a Integrações e clique em Ligar no cartão Webhook.

Passo 2: Preencha os dados

Na janela Configuração do webhook:

URL do endpoint: o endereço https do seu sistema que deve receber as mensagens.
Autorização: escolha Bearer e escreva um token à sua escolha, ou escolha Nenhuma.
Eventos: assinale os que pretende. Tem de escolher pelo menos um.

Depois, guarde, e o seu webhook fica ativo.

💡 Dica: Escolha Bearer e um token longo e aleatório. Assim, todas as mensagens incluem o cabeçalho Authorization: Bearer seguido do seu token, para que o seu sistema possa confirmar que a mensagem veio mesmo da Loyaltify. Este token é diferente da sua chave de API.

Alterar mais tarde

Pode alterar o endpoint, a autorização e os eventos a qualquer momento na página Configuração do webhook. Clique em Guardar quando terminar.

Eventos que pode escolher

Cliente criado (customer.created): um novo cliente adere.
Cliente atualizado (customer.updated): os dados de um cliente são editados.
Transação criada (transaction.created): um cliente recebe o saldo inicial, ganha, resgata, recebe uma recompensa de recomendação ou tem pontos que expiram.
Tentativa de inscrição de cliente existente (customer.signup_attempt): alguém que já tem o cartão volta a preencher o seu formulário. Os dados guardados não são alterados pelo novo envio.

O que contém cada mensagem

A Loyaltify envia cada mensagem em JSON, com os cabeçalhos Content-Type: application/json e User-Agent: Loyaltify-Webhook/1.0. Todas as mensagens têm três partes:

event: o evento em causa, como customer.created.
timestamp: quando aconteceu, em UTC (por exemplo 2026-10-16T16:38:46Z).
data: os detalhes, que dependem do evento.

Os números, como point e balance_after, são enviados como texto, por exemplo "1.0", e os valores vazios são null.

Cliente criado e Cliente atualizado

name, email, phone e birthday
uuid: o ID do cliente (o mesmo que está no código QR do cartão)
point: o saldo (em Cliente criado, o saldo inicial)
custom_fields: as respostas às suas perguntas personalizadas, incluindo valores ocultos do link do formulário, como click_id
is_marketing_opted_in: se o cliente deu consentimento de marketing
created_at, updated_at e store_uuid

Cliente atualizado inclui os mesmos campos, com os novos valores. Eis um exemplo de Cliente criado:

{
  "data": {
    "name": "Alex",
    "uuid": "7f3e9a21",
    "email": "[email protected]",
    "phone": null,
    "point": "1.0",
    "birthday": null,
    "created_at": "2026-10-16T16:38:41.704Z",
    "store_uuid": "a1b2c3d4",
    "updated_at": "2026-10-16T16:38:46.790Z",
    "custom_fields": {},
    "is_marketing_opted_in": true
  },
  "event": "customer.created",
  "timestamp": "2026-10-16T16:38:46Z"
}

Transação criada

kind: o tipo de transação, por exemplo initial (o saldo inicial no registo), manual, redeem, expired, referee ou referrer
point e amount: os valores da transação. Nas expirações, point é negativo.
balance_after: o saldo do cliente após a transação
campaign: nos resgates, a campanha resgatada
user: o membro da equipa que digitalizou (nome, ID e e-mail), ou null nos eventos automáticos, como as expirações
customer_uuid, customer_email e customer_phone
referred_by_uuid: nas recompensas de recomendação, quem recomendou o cliente
uuid: o ID da própria transação
created_at e store_uuid

Eis um exemplo de um membro da equipa a adicionar um ponto:

{
  "data": {
    "kind": "manual",
    "user": {
      "name": "Sam Taylor",
      "uuid": "0b8e7d4c-1f2a-4c3b-9d5e-6a7b8c9d0e1f",
      "email": "[email protected]"
    },
    "uuid": "5c9d2e7a-3b4f-4a1c-8e6d-2f7a9b0c1d3e",
    "point": "1.0",
    "amount": null,
    "campaign": null,
    "created_at": "2026-10-16T16:45:10.375Z",
    "store_uuid": "a1b2c3d4",
    "balance_after": "2.0",
    "customer_uuid": "7f3e9a21",
    "customer_email": "[email protected]",
    "customer_phone": null,
    "referred_by_uuid": null
  },
  "event": "transaction.created",
  "timestamp": "2026-10-16T16:45:10Z"
}

Uma recompensa de recomendação envia duas transações ao mesmo tempo: referee para o novo cliente, com referred_by_uuid preenchido com o ID do referente, e referrer para o cliente que o recomendou.

Tentativa de inscrição de cliente existente

customer: quem é o cliente existente, com o respetivo uuid e custom_fields
matched_on: como foi reconhecido, por exemplo pelo e-mail
submission: o que acabou de introduzir no formulário
form: o formulário que usou

Para ver uma mensagem completa, abra qualquer entrega em Eventos recentes (ver abaixo).

Verificar as entregas

A página Configuração do webhook mostra os seus Eventos recentes com o estado, o código de resposta, o número de tentativas e a data. Clique no ícone do olho para ver exatamente o que foi enviado, os cabeçalhos e a resposta do seu sistema.

As mensagens não estão a chegar?

Verifique se o URL do endpoint é um endereço https válido. Por vezes, os navegadores preenchem automaticamente esse campo com um endereço de e-mail.
Verifique se o evento está assinalado na página Configuração do webhook.
Verifique se está no plano Advanced.
Consulte o evento em Eventos recentes. Se o código de resposta indicar um erro, o seu sistema recebeu a mensagem mas rejeitou-a, e o ícone do olho mostra a resposta.

Continua com dificuldades? Contacte o apoio através do chat ao vivo.

Convém saber

As mensagens podem não chegar por ordem, por isso use o timestamp se a ordem for importante.
Prepare o seu sistema para receber o mesmo evento duas vezes, por precaução. Nas transações, o uuid em data é único para cada uma.
Trabalha com a API? Os webhooks enviam o ID curto do cliente. Alguns pedidos da API precisam antes do número interno do cliente, e a documentação da API mostra como obter um a partir do outro.
Usa a Omnisend? O guia da própria Omnisend usa um webhook para se ligar à Loyaltify. Consulte a Visão geral das integrações para encontrar o link.

Precisa de ajuda?

Estamos aqui para ajudar!

Se tiver alguma dúvida sobre os webhooks, fale connosco através do chat ao vivo na Loyaltify ou utilize o botão de chat no canto inferior direito desta página. A nossa equipa terá todo o gosto em ajudar.