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": "ref_xxx",
  "merchantId": "merch_xxx",
  "referrerId": "memb_xxx",
  "campaignId": "camp_xxx",
  "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": "memb_xxx",
    "name": "João",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "referralCode": "NUT-JOAO-ABCD"
  },
  "campaign": {
    "id": "camp_xxx",
    "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 um timestamp e a assinatura: t=1707048000,v1=5257a869e7ecebea3274212c...

Exemplo de validação em Node.js:

const crypto = require('crypto')

function verifyWebhook(payload, header, secret) {
  const [t, v1] = header.split(',')
  const timestamp = t.split('=')[1]
  const signature = v1.split('=')[1]

  const signedPayload = `${timestamp}.${payload}`
  const hmac = crypto.createHmac('sha256', secret)
  const expectedSignature = hmac.update(signedPayload).digest('hex')

  return signature === expectedSignature
}

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)

Outbound Webhooks

On this page