Skip to main content
Este documento descreve a estrutura JSON dos payloads de webhook enviados pelo sistema de Fidelidade para o seu endpoint registrado quando eventos específicos ocorrem.

​
Estrutura Base do Webhook

Todas as notificações de webhook entregues ao seu endpoint seguirão este formato JSON básico: 
{
  "Uuid": "uma_string_identificadora_unica",
  "Timestamp": "2025-04-15T14:30:00Z",
  "Topic": "Nome_Real_Do_Topico",
  "Payload": { ... }
}
​
Uuid
string
required
Identificador único (UUID) para esta tentativa de entrega. Use para idempotência.Exemplo: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
​
Timestamp
string
required
Data e hora (ISO 8601, UTC) em que o evento ocorreu.Exemplo: "2025-04-15T14:30:00.123Z"
​
Topic
string
required
Tipo de evento que ocorreu. Determina a estrutura do Payload.Exemplo: "Communication_EarnPurchasePoints"
​
Payload
object
required
Objeto JSON com os detalhes específicos do evento. A estrutura varia conforme o Topic.

​
Objetos de Dados Comuns

Estes objetos JSON aparecem frequentemente dentro de diferentes estruturas de Payload:
Contém informações sobre o cliente relacionado ao evento.
{
  "Email": "[email protected]",
  "Id": "id_original_cliente_123",
  "Name": "João Silva",
  "Phone": "+5511999998888",
  "Document": "12345678900",
  "BirthdayDate": "1990-05-20T00:00:00Z",
  "PointsBalance": 1500
}
​
Email
string
required
Endereço de e-mail principal do cliente
​
Id
string
required
Identificador único do cliente no sistema de origem (ex: plataforma e-commerce)
​
Name
string
required
Nome completo do cliente
​
Phone
string
required
Número de telefone com código do país
​
Document
string
Documento de identificação (ex: CPF), se fornecido. Pode ser null.
​
BirthdayDate
string
Data de nascimento (ISO 8601), se fornecida. Pode ser null.
​
PointsBalance
number
required
Saldo de pontos no momento do evento (pode não refletir o saldo após o evento)
Contém o saldo de pontos e cashback do cliente após o evento ter sido processado.
{
  "PointsBalance": 1650,
  "CashbackBalance": 16.50
}
​
PointsBalance
number
required
Saldo total de pontos após os efeitos do evento
​
CashbackBalance
number
required
Saldo total de cashback (decimal) após os efeitos do evento

​
Definições de Enum

Vários campos do payload representam tipos enumerados, enviados como inteiros no JSON.
Indica o tipo de um cupom.
ValorNomeDescrição
0FixedValueValor fixo (ex: R$ 10,00 de desconto)
1PercentValor percentual (ex: 10% de desconto)
2FreeShippingFrete grátis
3DiscountShippingDesconto em frete
4OthersOutros tipos (frequentemente pré-gerados)

​
Garantias de Entrega

Idempotência

Cada entrega inclui um Uuid único. Armazene e verifique para evitar processamento duplicado.

Retentativas

Entregas falhas são retentadas automaticamente com backoff crescente.

Timeout

O sistema espera até 30 segundos por uma resposta HTTP 2xx.

Desativação

Após 5+ falhas consecutivas, a assinatura pode ser desativada automaticamente.
Recomendações:
  • Responda com HTTP 2xx idealmente em poucos segundos
  • Processe o payload de forma assíncrona para evitar timeouts
  • Monitore falhas e reative assinaturas conforme necessário

​
Personalização

Ao configurar sua assinatura de webhook, você pode personalizar:

Corpo Personalizado

Defina uma estrutura JSON customizada usando linguagem de template

Variáveis na URL

Use variáveis do payload na URL (ex: https://endpoint.com/{{Customer.Id}})

Método HTTP

Especifique PUT, POST, etc. (padrão: POST)

Cabeçalhos

Configure headers estáticos para autenticação ou roteamento

​
Considerações de Segurança

Sempre siga as melhores práticas de segurança ao implementar webhooks.
1

Use HTTPS

Sempre use https:// para criptografia em trânsito
2

Mantenha o sigilo do endpoint

Mantenha a URL do endpoint difícil de adivinhar
3

Configure um segredo compartilhado

Configure um header customizado (ex: X-Loyalty-Secret) com um valor secreto e valide em cada requisição recebida

​
Lista de Todos os Tópicos Disponíveis

Referência rápida de todos os 26 tópicos de webhook disponíveis:
TópicoDescrição
Communication_EarnPurchasePointsPontos por compra
Communication_EarnBirthdayPointsPontos por aniversário
Communication_EarnSignupPointsPontos por cadastro
Communication_EarnReviewPointsPontos por review
Communication_ReferralCommunicationPointsPontos por indicação
Communication_EarnQuizPointsPontos por quiz
Communication_EarnCustomObjectivePointsPontos por objetivo customizado
Communication_EarnSocialMediaFollowInstagramPontos por seguir no Instagram
Communication_EarnSocialMediaFollowFacebookPontos por seguir no Facebook
Communication_EarnSocialMediaFollowLinkedinPontos por seguir no Linkedin
Communication_EarnSocialMediaFollowTikTokPontos por seguir no TikTok
Documentação atualizada em Dezembro de 2025.