Skip to main content
Este guia explica como criar e configurar uma assinatura de webhook na plataforma BonifiQ através do painel administrativo.

​
Acessando a Configuração de Webhooks

  1. Acesse o painel administrativo da BonifiQ
  2. No menu lateral, navegue até Configurações > Webhooks
  3. Clique no botão Criar Nova Assinatura

​
Campos do Formulário

​
Informações Básicas

Digite um nome descritivo para identificar esta assinatura de webhook.Exemplos:
  • Integração CRM
  • Notificações de Pedidos
  • Sincronização ERP
Use nomes que facilitem a identificação do propósito da integração.
Informe a URL completa que receberá as notificações de webhook.Exemplo: https://sua-api.com/webhooks/bonifiq
A URL deve:
  • Usar protocolo HTTPS (obrigatório para segurança)
  • Estar acessível publicamente na internet
  • Responder a requisições HTTP POST
Informe o e-mail que será notificado em caso de problemas com a entrega dos webhooks.Você receberá alertas quando:
  • Houver falhas consecutivas na entrega
  • A assinatura for desativada automaticamente
Defina se a assinatura está ativa ou pausada.
  • Ativo: A assinatura receberá notificações normalmente
  • Inativo: A assinatura está pausada e não receberá webhooks
Você pode desativar temporariamente uma assinatura sem precisar excluí-la.

​
Seleção de Eventos (Tópicos)

Selecione quais eventos você deseja receber. Você pode marcar um ou mais tópicos conforme a necessidade da sua integração.
EventoQuando é disparado
Ponto adicionadoQuando pontos são creditados para o cliente
Ponto removidoQuando pontos são debitados do cliente
Ponto atualizadoQuando um registro de ponto é modificado

​
Configurações Avançadas

Expanda a seção Configurações Avançadas para acessar opções adicionais.

​
Cabeçalhos HTTP (Headers)

Adicione cabeçalhos personalizados que serão enviados junto com cada requisição de webhook. Uso comum: Autenticação da requisição Clique em Adicionar Header e preencha:
  • Nome: Nome do cabeçalho (ex: X-API-Key, Authorization)
  • Valor: Valor do cabeçalho (ex: seu-token-secreto)
Dica de Segurança: Configure um header secreto (como X-Bonifiq-Secret) e valide esse valor no seu sistema para garantir que a requisição realmente veio da BonifiQ.
Exemplos de headers comuns:
NomeValorUso
X-API-Keyminha-chave-secretaAutenticação simples
AuthorizationBearer meu-tokenAutenticação OAuth
X-Bonifiq-Secretsegredo-compartilhadoValidação de origem

​
Método HTTP

Por padrão, as requisições são enviadas via POST. Se seu sistema requer outro método, selecione:
  • POST (padrão e recomendado)
  • PUT
  • PATCH

​
Corpo Personalizado

Esta é uma opção avançada. Na maioria dos casos, recomendamos usar o payload padrão.
Se seu sistema precisa receber os dados em um formato específico diferente do padrão, você pode ativar o Corpo Personalizado.
  1. Marque a opção Usar corpo personalizado
  2. No campo de texto, escreva seu template JSON usando variáveis entre {{chaves}}
Exemplo de template personalizado: 
{
  "tipo_evento": "{{Topic}}",
  "cliente": {
    "email": "{{Customer.Email}}",
    "nome": "{{Customer.Name}}"
  },
  "pontos_ganhos": {{EarnedPoints}},
  "data": "{{Timestamp}}"
}
Variáveis disponíveis:
VariávelDescrição
{{Customer.Email}}E-mail do cliente
{{Customer.Name}}Nome do cliente
{{Customer.Id}}ID do cliente
{{Customer.Phone}}Telefone do cliente
{{Customer.PointsBalance}}Saldo de pontos
{{EarnedPoints}}Pontos ganhos no evento
{{OrderId}}ID do pedido
{{OrderTotal}}Valor do pedido
{{CouponCode}}Código do cupom
{{Topic}}Nome do evento
{{Timestamp}}Data/hora do evento
{{Uuid}}ID único do webhook

​
Salvando a Assinatura

Após preencher todos os campos:
  1. Revise as informações
  2. Clique em Salvar
  3. A assinatura será criada e começará a receber eventos imediatamente (se marcada como ativa)

​
Gerenciando Assinaturas

Na lista de assinaturas, você pode:

Editar

Modifique configurações de uma assinatura existente

Pausar/Ativar

Desative temporariamente ou reative uma assinatura

Excluir

Remova permanentemente uma assinatura

​
Requisitos do seu Endpoint

Para receber os webhooks corretamente, seu endpoint deve:
1

Aceitar requisições HTTPS

O endpoint deve ter um certificado SSL válido
2

Responder rapidamente

Retorne HTTP 200 (OK) em poucos segundos, idealmente em até 5 segundos
3

Processar de forma assíncrona

Receba o webhook, salve/enfileire e responda. Processe os dados depois.
4

Implementar idempotência

Use o campo Uuid para evitar processar o mesmo evento duas vezes
Se o seu endpoint falhar consecutivamente (5+ vezes), a assinatura será automaticamente desativada e o responsável será notificado por e-mail.