Webhooks

Receba notificações em tempo real sobre eventos importantes da sua conta FlowMail. Configure endpoints para receber payloads JSON automaticamente quando eventos ocorrerem.

Eventos Disponíveis

Atualmente, o FlowMail suporta os seguintes eventos de webhook:

Evento	Descrição	Quando dispara
`bulk_job.completed`	Verificação em lote finalizada	Quando um job de verificação em lote termina o processamento
`quota.warning`	Alerta de cota (80%)	Quando sua conta atinge 80% da cota mensal de verificações
`quota.exceeded`	Cota excedida	Quando sua conta atinge 100% da cota mensal

Configuração

Para configurar webhooks, acesse o Dashboard e navegue até Configurações → Webhooks. Você pode:

Adicionar uma URL de endpoint (deve ser HTTPS)
Selecionar quais eventos deseja receber
Gerar um segredo de assinatura para validar as requisições
Testar o endpoint com um payload de exemplo

Payloads de Exemplo

bulk_job.completed

Enviado quando um job de verificação em lote finaliza o processamento de todos os e-mails.

JSON

{
  "event": "bulk_job.completed",
  "timestamp": "2026-03-02T14:30:00Z",
  "data": {
    "job_id": "job_abc123def456",
    "total_emails": 5000,
    "results": {
      "valid": 3200,
      "invalid": 1100,
      "risky": 450,
      "unknown": 250
    },
    "duration_seconds": 127,
    "created_at": "2026-03-02T14:27:53Z",
    "completed_at": "2026-03-02T14:30:00Z"
  }
}

quota.warning

Enviado quando sua conta atinge 80% da cota mensal de verificações.

JSON

{
  "event": "quota.warning",
  "timestamp": "2026-03-02T10:15:00Z",
  "data": {
    "plan": "pro",
    "quota_limit": 100000,
    "quota_used": 80500,
    "percentage_used": 80.5,
    "resets_at": "2026-04-01T00:00:00Z"
  }
}

quota.exceeded

Enviado quando sua conta atinge 100% da cota mensal. Novas verificações serão rejeitadas com status 429.

JSON

{
  "event": "quota.exceeded",
  "timestamp": "2026-03-15T18:42:00Z",
  "data": {
    "plan": "pro",
    "quota_limit": 100000,
    "quota_used": 100000,
    "percentage_used": 100.0,
    "resets_at": "2026-04-01T00:00:00Z",
    "upgrade_url": "https://mail.flowsales.online/dashboard/billing"
  }
}

Headers de Segurança

Todas as requisições de webhook incluem headers especiais para que você possa verificar a autenticidade da chamada.

Header	Descrição
`X-FlowMail-Signature`	Assinatura HMAC SHA-256 do corpo da requisição, usando seu segredo de webhook
`X-FlowMail-Event`	Nome do evento (ex: `bulk_job.completed`)

Verificação da Assinatura

Sempre verifique a assinatura para garantir que a requisição realmente veio do FlowMail. O header X-FlowMail-Signature contém o HMAC SHA-256 do corpo da requisição, gerado com o segredo que você configurou no dashboard.

PHP

<?php

$webhookSecret = env('FLOWMAIL_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FLOWMAIL_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Assinatura inválida']);
    exit;
}

// Assinatura válida, processar o evento
$event = json_decode($payload, true);
$eventType = $_SERVER['HTTP_X_FLOWMAIL_EVENT'] ?? '';

switch ($eventType) {
    case 'bulk_job.completed':
        // Processar conclusão do job em lote
        break;
    case 'quota.warning':
        // Notificar equipe sobre cota
        break;
    case 'quota.exceeded':
        // Pausar envios, notificar admin
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

Retentativas

Se o seu endpoint retornar um código HTTP diferente de 2xx, o FlowMail tentará reenviar a notificação até 3 vezes com backoff exponencial:

Tentativa	Intervalo	Tempo acumulado
1ª retentativa	30 segundos	30s após a falha
2ª retentativa	5 minutos	~5min30s após a falha
3ª retentativa	30 minutos	~35min30s após a falha

Importante

Após 3 tentativas sem sucesso, o webhook será marcado como falhado no dashboard. Se um endpoint falhar consistentemente, ele será desativado automaticamente após 10 falhas consecutivas. Você receberá um e-mail de notificação quando isso ocorrer.