Rifa Digital

Webhooks

Neste guia, você aprenderá como configurar webhooks para integrar seu sistema com a Rifa Digital. Com webhooks, seu sistema pode ser notificado em tempo real quando algo acontece com as reservas, como uma nova compra ou confirmação de pagamento.

Configurando webhooks

Para configurar webhooks, acesse Configurações > Webhooks no painel do organizador. Você precisará fornecer:

  • URL do Webhook: O endpoint HTTPS que receberá as notificações
  • Token de Autenticação: Uma chave secreta com no mínimo 16 caracteres
  • Eventos: Quais eventos devem acionar o webhook

Ao salvar a configuração, um teste de conexão (ping) é realizado. Seu endpoint deve responder com status 2xx e incluir o header X-Api-Key com o mesmo token enviado.

Tipos de eventos

  • Nome
    order.created
    Descrição

    Uma nova reserva foi criada. Inclui o campo expires_at indicando quando a reserva expira.

  • Nome
    order.paid
    Descrição

    Uma reserva foi confirmada como paga. Os números sorteados já estão atribuídos ao cliente.

  • Nome
    order.expired
    Descrição

    Uma reserva expirou sem pagamento e foi cancelada automaticamente.

Exemplo de payload

{
  "event": "order.paid",
  "timestamp": "2024-01-15T10:30:45.000000Z",
  "data": {
    "order": {
      "uuid": "01HQXYZ123ABC",
      "currency": "BRL",
      "amount": 50.00,
      "numbers": [7, 15, 23, 42, 99],
      "numbers_count": 5,
      "customer_name": "João Silva",
      "customer_email": "[email protected]",
      "customer_phone": "11999999999",
      "created_at": "2024-01-15T10:25:00.000000Z"
    },
    "raffle": {
      "slug": "iphone-15-pro",
      "name": "iPhone 15 Pro Max"
    }
  }
}

Estrutura do payload

Cada notificação de webhook contém as seguintes informações:

  • Nome
    event
    Tipo
    string
    Descrição

    O tipo do evento: order.created, order.paid ou order.expired.

  • Nome
    timestamp
    Tipo
    string
    Descrição

    Data e hora do evento no formato ISO 8601.

  • Nome
    data.order
    Tipo
    object
    Descrição

    Informações da reserva incluindo UUID, valor, números e dados do cliente.

  • Nome
    data.raffle
    Tipo
    object
    Descrição

    Informações da campanha (slug e nome). Pode ser null se a campanha foi excluída.

Campos da reserva

  • Nome
    uuid
    Tipo
    string
    Descrição

    Identificador único da reserva.

  • Nome
    currency
    Tipo
    string
    Descrição

    Moeda da reserva (ex: BRL).

  • Nome
    amount
    Tipo
    number
    Descrição

    Valor total da reserva.

  • Nome
    numbers
    Tipo
    array
    Descrição

    Lista de números adquiridos. Pode ser null para reservas não pagas.

  • Nome
    numbers_count
    Tipo
    integer
    Descrição

    Quantidade de números na reserva.

  • Nome
    customer_name
    Tipo
    string
    Descrição

    Nome do cliente.

  • Nome
    customer_email
    Tipo
    string
    Descrição

    E-mail do cliente.

  • Nome
    customer_phone
    Tipo
    string
    Descrição

    Telefone do cliente.

  • Nome
    expires_at
    Tipo
    string
    Descrição

    Data de expiração da reserva. Presente apenas no evento order.created.

Autenticação

Cada requisição de webhook inclui os seguintes headers para verificação:

X-Api-Key: seu_token_secreto
X-Webhook-Event: order.paid
X-Webhook-Delivery: 01HQXYZ789DEF
Content-Type: application/json

Verificando a autenticação

// PHP
$token = $_SERVER['HTTP_X_API_KEY'] ?? '';
$expectedToken = 'seu_token_configurado';

if ($token !== $expectedToken) {
    http_response_code(401);
    exit('Token inválido');
}

// Processar o webhook...
$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['event'];
$data = $payload['data'];

Teste de conexão (Ping)

Ao salvar a configuração do webhook, um teste de conexão é realizado automaticamente. Seu endpoint deve:

  1. Responder com status HTTP 2xx (200, 201, etc.)
  2. Incluir o header X-Api-Key na resposta com o mesmo token recebido

É obrigatório que seu endpoint retorne o header X-Api-Key na resposta. Sem isso, o teste de conexão falhará.

Payload do ping

{
  "event": "ping",
  "timestamp": "2024-01-15T10:30:45.000000Z"
}

Respondendo ao ping

// PHP
$token = $_SERVER['HTTP_X_API_KEY'] ?? '';
header('X-Api-Key: ' . $token);
http_response_code(200);
echo json_encode(['status' => 'ok']);

Tentativas e retentativas

Se seu endpoint não responder com sucesso (status 2xx), o sistema tentará novamente:

  • Máximo de tentativas: 3
  • Intervalo entre tentativas: 60s, 120s, 240s (backoff exponencial)
  • Timeout: 30 segundos por requisição

O histórico de entregas pode ser visualizado na página de configuração do webhook, mostrando o status, tentativas e erros de cada notificação.

Use o header X-Webhook-Delivery para identificar entregas duplicadas e implementar idempotência no seu sistema.

Integrando com n8n

O n8n é uma ferramenta de automação que permite criar fluxos de trabalho visuais. Você pode usar o n8n para receber webhooks da Rifa Digital e automatizar ações como enviar notificações, atualizar planilhas ou integrar com outros sistemas.

Configurando o webhook no n8n

  1. Crie um novo workflow no n8n
  2. Adicione o node Webhook como trigger
  3. Configure o node:
    • HTTP Method: POST
    • Path: escolha um caminho único (ex: rifa-digital)
    • Authentication: Header Auth
  4. Em Credential for Header Auth, clique em Create New Credential:
    • Name: Rifa Digital Webhook
    • Header Name: X-Api-Key
    • Header Value: crie um token seguro com no mínimo 16 caracteres
    • Clique em Save
  5. Clique em Listen for Test Event para obter a URL
  6. Copie a URL (ex: https://seu-n8n.com/webhook/rifa-digital)

Use Credenciais para salvar o token em vez de colocá-lo diretamente no node. Isso mantém o token seguro e permite reutilizá-lo em outros workflows.

Configurando na Rifa Digital

  1. Acesse Configurações > Webhooks
  2. Cole a URL do n8n no campo URL do Webhook
  3. Use o mesmo token configurado no n8n como Token de Autenticação
  4. Selecione os eventos desejados
  5. Salve a configuração

O n8n precisa estar rodando e o workflow ativo para receber os webhooks. Use a opção Production URL para um endpoint permanente.

Respondendo ao ping

Para que o teste de conexão funcione, adicione um node Respond to Webhook após o node Webhook:

  1. Adicione o node Respond to Webhook
  2. Configure:
    • Respond With: JSON
    • Response Body: { "status": "ok" }
  3. Em Options > Response Headers, adicione:
    • Name: X-Api-Key
    • Value: use uma expressão para retornar o header recebido: {{ $request.headers['x-api-key'] }}

Exemplo de workflow

Após receber o webhook, você pode adicionar nodes para:

  • IF: Filtrar por tipo de evento (order.paid, order.created, etc.)
  • Google Sheets: Registrar vendas em uma planilha
  • Telegram/WhatsApp: Enviar notificações de novas vendas
  • HTTP Request: Integrar com outros sistemas

Esta página foi útil?