Introdução - BonifiQ Developers

Webhooks permitem que sua integração receba eventos da BonifiQ assim que eles acontecem, sem consultar a API repetidamente. Use-os para sincronizar clientes, pedidos, transações de pontos, comunicações e indicações de afiliados com seus próprios sistemas.

Como Funciona

Um Evento Ocorre

Uma operação na BonifiQ, como a criação de um cliente, o registro de um pedido ou uma alteração de pontos, gera um evento.

A BonifiQ Prepara a Notificação

O evento recebe um Uuid, um tópico e o payload correspondente. O mesmo Uuid é preservado caso a entrega precise ser repetida.

A Notificação é Enviada

A BonifiQ chama a URL configurada usando o método HTTP e os headers definidos na assinatura.

Seu Endpoint Confirma o Recebimento

Valide o header secreto e salve ou enfileire o payload. Ao usar o envelope padrão, registre o Uuid de forma durável e responda com HTTP 2xx.

Falhas Transitórias são Repetidas

Quando a entrega falha de forma transitória, a BonifiQ tenta novamente com backoff exponencial.

Processe o evento de forma assíncrona depois de confirmar o recebimento. Com o envelope padrão, se o Uuid já tiver sido registrado, trate a entrega como duplicada e responda com 2xx sem processá-la novamente.

Comece por Aqui

Configurar uma Assinatura

Crie o webhook, escolha os tópicos e configure URL, método e autenticação.

Comunicações

Eventos de ganho e resgate de pontos, cupons, tiers, objetivos e OTP.

Transações de Pontos

Inclusão, atualização e remoção de pontos.

Pedidos

Criação e atualização de pedidos.

Afiliados

Pontos concedidos por indicação de afiliados.

Clientes

Criação e atualização de clientes.

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": 3,
  "TopicName": "Communication_EarnPurchasePoints",
  "Payload": { ... }
}

string

required

Identificador único do evento. Ele permanece igual durante as retentativas de entrega e deve ser usado para idempotência.Exemplo: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

string

required

Data e hora (ISO 8601, UTC) em que o evento de webhook foi criado na BonifiQ.Exemplo: "2025-04-15T14:30:00.123Z"

number

required

Código numérico do tipo de evento (enum). Veja a Lista de Tópicos.Exemplo: 3 (Communication_EarnPurchasePoints)

string

required

Nome do tipo de evento como string. Determina a estrutura do Payload.Exemplo: "Communication_EarnPurchasePoints"

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:

Objeto Cliente (Customer)

Contém informações sobre o cliente relacionado ao evento.

{
  "Email": "cliente@exemplo.com",
  "Id": "id_original_cliente_123",
  "Name": "João Silva",
  "Phone": "+5511999998888",
  "Document": "12345678900",
  "BirthdayDate": "1990-05-20T00:00:00Z",
  "PointsBalance": 1500,
  "Rfm": {
    "Recency": 5,
    "Frequency": 3,
    "Monetary": 4,
    "Score": "534"
  }
}

string

required

Endereço de e-mail principal do cliente

string

required

Identificador único do cliente no sistema de origem (ex: plataforma e-commerce)

string

required

Nome completo do cliente

string

required

Número de telefone com código do país

string

Documento de identificação (ex: CPF), se fornecido. Pode ser null.

string

Data de nascimento (ISO 8601), se fornecida. Pode ser null.

number

required

Saldo de pontos no momento do evento (pode não refletir o saldo após o evento)

object

Dados RFM (Recency, Frequency, Monetary) do cliente, se disponível. Pode ser null.

Objeto Saldo de Pontos (PointsBalance)

Contém o saldo de pontos e cashback do cliente após o evento ter sido processado.

{
  "PointsBalance": 1650,
  "CashbackBalance": 16.50
}

number

required

Saldo total de pontos após os efeitos do evento

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.

CouponType
ObjectiveType
PointType
PointAction

Indica o tipo de um cupom.

Valor	Nome	Descrição
`0`	FixedValue	Valor fixo (ex: R$ 10,00 de desconto)
`1`	Percent	Valor percentual (ex: 10% de desconto)
`2`	FreeShipping	Frete grátis
`3`	DiscountShipping	Desconto em frete
`4`	Others	Outros tipos (frequentemente pré-gerados)

Indica a razão ou atividade que disparou o evento (ganho de pontos).

Valor	Nome	Descrição
`0`	Purchase	Fazer uma compra
`1`	Signup	Criar conta
`2`	Birthday	Fazer aniversário
`3`	Review	Fazer um review
`4`	Referral	Indique um amigo(a)
`5`	SocialMediaFollowInstagram	Siga no Instagram
`6`	SocialMediaFollowFacebook	Siga no Facebook
`7`	Quiz	Responda um Quiz
`8`	Custom	Objetivo Customizado
`9`	SocialMediaFollowLinkedin	Siga no Linkedin
`10`	SocialMediaFollowTikTok	Siga no TikTok
`11`	Participation	Participação

Especifica a razão detalhada para uma transação de ponto.

Valor	Nome	Descrição
`0`	Purchase	Fez uma compra
`1`	Signup	Criou conta
`2`	Birthday	Fez aniversário
`3`	Ordinary	Concedido por administrador
`4`	Reward	Trocou por recompensa
`5`	Review	Fez um review
`6`	Refund	Reembolso de pontos
`7`	Expire	Pontos expirados
`8`	Referral	Indicou um amigo
`9`	SocialMediaFollowFacebook	Seguiu no Facebook
`10`	SocialMediaFollowInstagram	Seguiu no Instagram
`11`	PartialOrderRefund	Reembolso parcial de pedido
`12`	Quiz	Respondeu um quiz
`13`	CustomObjective	Pontos de objetivo personalizado
`14`	ReferralAffiliate	Indicação de afiliado
`15`	SocialMediaFollowLinkedin	Seguiu no Linkedin
`16`	SocialMediaFollowTikTok	Seguiu no TikTok
`17`	Campaign	Campanha

Indica se pontos foram adicionados ou removidos.

Valor	Nome	Descrição
`0`	Take	Pontos removidos ou gastos
`1`	Grant	Pontos adicionados ou concedidos

Garantias de Entrega

Confirmação

Qualquer resposta HTTP 2xx confirma que o evento foi recebido com sucesso.

Idempotência

O mesmo Uuid é enviado em todas as tentativas do evento. Armazene e verifique esse valor para evitar processamento duplicado.

Retentativas

Falhas transitórias são retentadas automaticamente com backoff exponencial.

Timeout

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

Por padrão, a BonifiQ realiza até 5 tentativas de entrega, incluindo a primeira chamada. Esse limite pode variar conforme a configuração do ambiente. Se o limite for atingido, a assinatura pode ser desativada e o e-mail técnico configurado é notificado.

Respostas HTTP 400, 404 e 405 são tratadas como falhas permanentes para aquele evento. Nesses casos, a BonifiQ interrompe suas retentativas sem desativar automaticamente a assinatura por essa única resposta.

Monitore a área Últimos eventos enviados no painel para acompanhar o status, o número de tentativas, o payload e eventuais erros.

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

Ao ativar um corpo personalizado, ele substitui completamente o envelope padrão com Uuid, Timestamp, Topic, TopicName e Payload. As variáveis disponíveis no template pertencem ao payload do tópico selecionado. Prefira o envelope padrão quando precisar deduplicar entregas pelo identificador do evento.

Considerações de Segurança

A BonifiQ envia os headers estáticos configurados na assinatura, mas não adiciona uma assinatura HMAC nativa ao payload. A validação do segredo compartilhado deve ser implementada pelo seu endpoint.

Use HTTPS

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

Mantenha o sigilo do endpoint

Não exponha a URL nem os headers de autenticação em logs, repositórios ou código público.

Configure um segredo compartilhado

Configure um header customizado, como X-Bonifiq-Secret, e compare seu valor em todas as requisições recebidas.

Referência dos Tópicos

Os 29 tópicos disponíveis estão organizados por domínio. Consulte a página correspondente para ver quando cada evento é disparado e a estrutura completa do seu Payload.

Comunicações

Ganho e resgate de pontos, cupons, tiers, objetivos, participação, redes sociais e OTP.

Transações de Pontos

Eventos Point_Add, Point_Update e Point_Removed.

Pedidos

Eventos OrderInsert e OrderUpdate.

Afiliados

Pontos concedidos por indicação de afiliados.

Clientes

Eventos Customer_Created e Customer_Updated.

​Como Funciona

​Comece por Aqui

Configurar uma Assinatura

Comunicações

Transações de Pontos

Pedidos

Afiliados

Clientes

​Estrutura Base do Webhook

​Objetos de Dados Comuns

​Definições de Enum

​Garantias de Entrega

Confirmação

Idempotência

Retentativas

Timeout

​Personalização

Corpo Personalizado

Variáveis na URL

Método HTTP

Cabeçalhos

​Considerações de Segurança

​Referência dos Tópicos

Comunicações

Transações de Pontos

Pedidos

Afiliados

Clientes

Como Funciona

Comece por Aqui

Estrutura Base do Webhook

Objetos de Dados Comuns

Definições de Enum

Garantias de Entrega

Personalização

Considerações de Segurança

Referência dos Tópicos