Configure webhooks para receber eventos de pedidos em tempo real do Guru e Yampi.

Webhooks

Rafobase usa webhooks para receber eventos de pedidos da sua plataforma de checkout. Quando um cliente usa um cupom de indicação, o checkout envia um webhook que ativa o processo de atribuição e recompensa.

Plataformas Suportadas

Plataforma	Eventos	Status
Guru	`transaction.approved`, `transaction.refunded`	✅ Suportado
Yampi	`order.paid`, `order.status.updated`	✅ Suportado

Como Funciona

Guia de Configuração

Configure a URL do Webhook

No seu painel de administração do Guru:

Vá para Configurações → Webhooks
Clique em Adicionar Webhook

Digite a URL:

https://api.rafobase.com/api/webhooks/guru/{SEU_MERCHANT_ID}

Selecione Eventos

Ative os seguintes eventos:

✅ transaction.approved - Quando o pagamento é confirmado
✅ transaction.refunded - Quando o pedido é reembolsado

O evento transaction.approved dispara a atribuição de indicação. O evento transaction.refunded cancela créditos pendentes.

Segurança

Webhooks do Guru não utilizam verificação de assinatura. A autenticação é feita pelo merchantId incluído na URL do webhook.

Teste a Integração

Crie um pedido de teste com um cupom de indicação
Verifique Painel Rafobase → Webhooks para o evento
Verifique se a indicação foi criada

Configure a URL do Webhook

No seu painel de administração do Yampi:

Vá para Configurações → Integrações → Webhooks

Adicione um novo endpoint de webhook:

https://api.rafobase.com/api/webhooks/yampi/{SEU_MERCHANT_ID}

Selecione Eventos

Ative os seguintes eventos:

✅ order.paid - Quando o pagamento é confirmado
✅ order.status.updated - Para reembolsos e cancelamentos

Configure o Segredo

Gere ou copie o segredo do webhook do Yampi
No Painel do Rafobase, vá para Configurações → Integrações → Yampi
Cole o segredo do webhook
Salve

Teste a Integração

Faça um pedido de teste usando um cupom de indicação
Monitore Painel Rafobase → Webhooks
Confirme que a indicação aparece corretamente

Exemplos de Carga de Webhook

Guru - Transação Aprovada

{
  "webhook_type": "transaction",
  "transaction": {
    "id": "trx_xxxxx",
    "status": "approved",
    "amount": 20000,
    "currency": "BRL",
    "customer": {
      "email": "newcustomer@example.com",
      "name": "Novo Cliente",
      "document": "12345678900"
    },
    "coupon": {
      "code": "NUT-JOHN-A7X"
    },
    "subscription_id": "sub_xxxxx",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Yampi - Pedido Pago

{
  "event": "order.paid",
  "data": {
    "id": 123456,
    "status": "paid",
    "total": 20000,
    "customer": {
      "email": "newcustomer@example.com",
      "name": "Novo Cliente",
      "cpf": "123.456.789-00"
    },
    "coupon_code": "NUT-JOHN-A7X",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Segurança de Webhook

Yampi - Verificação HMAC

Webhooks do Yampi incluem assinatura HMAC-SHA256 no header X-Yampi-Hmac-SHA256. Configure o segredo no painel do Rafobase em Configurações → Integrações → Yampi.

import crypto from 'crypto'

function verifyYampiSignature(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

Guru - Sem Assinatura

Webhooks do Guru não utilizam verificação de assinatura. A autenticação é feita pelo merchantId na URL do webhook. Mantenha a URL secreta.

O cabeçalho X-Rafobase-Signature é utilizado apenas para webhooks outbound (Rafobase → sistemas externos), não para webhooks inbound de plataformas de checkout.

Webhooks

On this page