Outbound Webhooks

O Rafobase pode enviar notificações (webhooks) para sistemas externos sempre que eventos importantes ocorrem no seu programa de indicação.

Esta é uma integração Outbound (Saindo da plataforma). Diferente dos webhooks de checkout (que entram), estes enviam dados DO Rafobase PARA outros sistemas.

🛠️ Casos de Uso

Notificações no Slack/Discord: Avise sua equipe sobre novas vendas por indicação.
CRM (HubSpot/Salesforce): Atualize o perfil do contato quando ele ganha comissão.
Automação (Zapier/n8n/Make): Crie fluxos complexos baseados em eventos.
Data Lake: Salve histórico de eventos para análise de dados.

📡 Eventos Disponíveis

Você pode se inscrever nos seguintes tópicos:

Evento	Descrição
`member.created`	Novo membro cadastrado no programa
`member.updated`	Dados do membro atualizados
`referral.created`	Nova indicação detectada (venda realizada)
`referral.approved`	Indicação confirmada (comissão creditada)
`referral.rejected`	Indicação rejeitada (fraude ou cancelamento)
`wallet.credit`	Crédito adicionado à carteira
`wallet.debit`	Débito/Saque realizado
`payout.requested`	Membro solicitou saque do saldo

⚙️ Configuração

Acessar Configurações

No Painel Administrativo, vá para Settings → Webhooks.

Adicionar Endpoint

Clique em "Add Endpoint" e preencha:

URL: O endereço onde receberá os eventos (ex: URL do seu workflow no n8n)
Description: Nome para identificar (ex: "Integração Slack")
Events: Selecione quais eventos deseja receber

Testar e Ativar

O sistema irá gerar um Signing Secret (guarded-o com segurança)
Use o botão "Test" para enviar um evento de exemplo
Verifique se sua ferramenta recebeu o dado corretamente

📦 Formato do Payload

Todos os webhooks seguem este formato padrão:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "f8e7d6c5-b4a3-2109-8765-43210fedcba9",
  "referrerId": "1a2b3c4d-5e6f-7890-abcd-1234567890ef",
  "campaignId": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
  "externalOrderId": "123",
  "refereeName": "Maria",
  "refereeEmail": "maria@example.com",
  "refereeCpf": "12345678900",
  "orderAmount": 218,
  "rewardAmount": 50,
  "couponUsed": "NUT-PAULO-5DAB5",
  "status": "pending",
  "rejectionReason": null,
  "warrantyEndsAt": "2026-02-22T17:45:58.369Z",
  "approvedAt": null,
  "cancelledAt": null,
  "cancellationReason": null,
  "createdAt": "2026-01-23T17:45:58.369Z",
  "updatedAt": "2026-01-23T17:45:58.369Z",
  "referee": {
    "name": "Maria",
    "email": "maria@example.com",
    "cpf": "12345678900"
  },
  "referrer": {
    "id": "1a2b3c4d-5e6f-7890-abcd-1234567890ef",
    "name": "João",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "referralCode": "NUT-JOAO-ABCD"
  },
  "campaign": {
    "id": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
    "name": "Campanha Verão",
    "rewardType": "percentage",
    "rewardValue": 10,
    "minOrderValue": 100,
    "maxRewardValue": 50,
    "warrantyDays": 7
  }
}

🔒 Segurança

Assinatura (HMAC SHA-256)

Para garantir que o webhook veio realmente do Rafobase, validamos a assinatura no header X-Rafobase-Signature.

O header contém o hash HMAC SHA-256 do payload:

X-Rafobase-Signature: sha256=5257a869e7ecebea3274212c...

Exemplo de validação em Node.js:

const crypto = require('crypto')

function verifyWebhook(payload, signatureHeader, secret) {
  const signature = signatureHeader.replace('sha256=', '')
  const hmac = crypto.createHmac('sha256', secret)
  const expectedSignature = hmac.update(payload).digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  )
}

Retries

Se o seu servidor retornar erro (não-200) ou timeout, o Rafobase tentará re-enviar:

Tentativas: Até 5 vezes
Estratégia: Backoff exponencial (espera mais tempo entre tentativas)

📬 Plataformas de Entrega

Além de endpoints customizados (HTTP), o sistema de webhook delivery do Rafobase também entrega eventos para:

Discord: Notificações automáticas via webhook do Discord (configurável em Settings → Discord)
Klaviyo: Sincronização de eventos como Metrics no Klaviyo (configurável em Settings → Klaviyo)

Todos os destinos passam pelo mesmo pipeline de entrega com retries e logging.

Outbound Webhooks

On this page