Webhook – Eventos de Cliente

Esta documentação descreve os novos eventos de webhook disponíveis no BonifiQ para integração com sistemas externos. Esses eventos são disparados sempre que um cliente é criado ou atualizado na plataforma.

A funcionalidade foi desenvolvida a partir de uma solicitação do cliente Mizuno, seguindo o mesmo padrão adotado no webhook de Matriz RFM.

Visão Geral

Os eventos de cliente permitem que sistemas integrados recebam, em tempo real, informações atualizadas sobre o cadastro dos clientes no BonifiQ, incluindo dados cadastrais e saldos de pontos e cashback.

Os eventos disponíveis são:

• Customer_Created – Disparado quando um novo cliente é cadastrado
• Customer_Updated – Disparado quando um cliente existente tem seus dados alterados

Estrutura Geral do Webhook

Todos os eventos seguem uma estrutura padrão de payload, composta pelos seguintes campos:

Evento: Cliente Criado (Customer_Created)

Quando é disparado

Este evento é disparado sempre que um novo cliente é cadastrado no BonifiQ.

Uso recomendado

• Sincronização de base de clientes
• Criação automática de clientes em sistemas externos (CRM, ERP, CDP, etc.)
• Atualização de plataformas de marketing

Payload – Exemplo

{
  "Uuid": "550e8400-e29b-41d4-a716-446655440001",
  "Timestamp": "2024-01-15T14:30:00.000000",
  "Topic": 0,
  "TopicName": "Customer_Created",
  "Payload": {
    "Customer": {
      "Email": "novo.cliente@example.com",
      "Id": "789012",
      "Name": "Maria Santos",
      "Phone": "11987654321",
      "Document": "12345678901",
      "BirthDate": "15/03/1990",
      "Level": "beginner",
      "Active": "sim"
    },
    "PointsBalance": {
      "PointsBalance": 0,
      "CashbackBalance": 0
    }
  }
 }
 

Campos do objeto Customer

Campos do objeto PointsBalance

Evento: Cliente Atualizado (Customer_Updated)

Quando é disparado

Este evento é disparado sempre que dados de um cliente existente são atualizados no BonifiQ.

Uso recomendado

• Manter dados sincronizados entre sistemas
• Atualizar informações cadastrais em CRMs
• Reprocessar segmentações e regras externas

Payload – Exemplo

{
  "Uuid": "550e8400-e29b-41d4-a716-446655440002",
  "Timestamp": "2024-01-15T14:30:00.000000",
  "Topic": 0,
  "TopicName": "Customer_Updated",
  "Payload": {
    "Customer": {
      "Email": "cliente@example.com",
      "Id": "123456",
      "Name": "João Silva Atualizado",
      "Phone": "11998877665",
      "Level": "intermediate"
    },
    "PointsBalance": {
      "PointsBalance": 1000,
      "CashbackBalance": 100
    }
  }
 }
 

Observações importantes

• Apenas os dados atualizados do cliente podem ser enviados no payload
• O saldo de pontos e cashback sempre reflete a posição atual do cliente no momento do disparo

Considerações Gerais

• Os eventos são enviados automaticamente para a URL de webhook configurada pelo cliente
• É responsabilidade do sistema integrador tratar falhas, retentativas e validações de segurança
• Recomenda-se validar o Uuid para evitar processamento duplicado

Suporte

Em caso de dúvidas sobre a configuração ou consumo dos webhooks, entre em contato com o time de suporte da BonifiQ.