Campaign Events API

Para que serve?

• Consultar o histórico completo de eventos de uma campanha pontual (envios, aberturas, cliques, denúncias, credenciais comprometidas, etc.) a partir dos teus próprios sistemas: reporting, dashboards internos, integrações com o teu SIEM.

Para a lista de campanhas com as suas estatísticas agregadas, ver API de Campanhas. Este artigo cobre apenas o detalhe evento a evento de uma campanha pontual.

Como se implementa?

Base URL: todos os endpoints vivem sob o prefixo {{base_url}}/api/companies/v1.

Para obter o host de produção (base_url), contacta o teu representante da Whalemate ou escreve-nos através do chat de suporte.

Autenticação: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Gera ou consulta a tua chave em Configuração → Integrações → cartão Chaves API → Chaves Ativas. Detalhe em Chaves API: como gerá-las, usá-las e revogá-las.

A empresa é resolvida automaticamente a partir da API Key: não envias company_id, e o endpoint só devolve eventos de campanhas que pertencem à tua empresa.

Endpoints

Eventos de uma campanha

GET {{base_url}}/api/companies/v1/campaigns/{id}/events

Devolve o histórico completo de eventos de uma campanha pontual (sem paginação).

Exemplo Request: GET {{base_url}}/api/companies/v1/campaigns/88/events

Resposta (200 OK):

{
  "data": [
    {
      "id": 4567,
      "date_time": "2026-03-05T09:15:32Z",
      "type": "Clicked Link",
      "ip": "192.168.1.45",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "victim": {
        "id": 789,
        "email": "[email protected]",
        "first_name": "Juan",
        "last_name": "Pérez",
        "department": "Finanzas",
        "position": "Analista Senior",
        "country": "México"
      }
    }
  ]
}

Ordenados por date_time descendente. Não inclui eventos do tipo Automatic Clicked (cliques automáticos de scanners de segurança corporativos, não da vítima), nem eventos posteriores ao fecho da campanha (closes_at), o mesmo corte aplicado pelas estatísticas da lista em API de Campanhas.

type pode ser qualquer um de: Email Sent, Failed, Clicked Link, Email Reported, Email Opened, Credential Harvesting, File Open, Download, Reported, Impersonated.

Resposta de erro (404), a campanha não existe ou não pertence à tua empresa:

{
  "message": "No query results for model [Src\\Domain\\Campaign\\Models\\Campaign]."
}

Erros comuns

Exemplo cURL

curl -X GET "https://api.whalemate.io/api/companies/v1/campaigns/88/events" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

❓ Perguntas frequentes

• Vem paginado? Não, todos os eventos da campanha são devolvidos de uma vez.

• Por que não vejo eventos do tipo Automatic Clicked? O endpoint exclui-os de propósito: são cliques automáticos de scanners/proxies de segurança corporativos, não da vítima, e sujariam as analíticas.

• Em que fuso horário vêm as datas? Em UTC, tal como o resto da Company API.

• Como consigo o id da campanha? Com a lista de API de Campanhas (GET /campaigns).

• Onde consigo a minha API Key? Em Configuração → Integrações → cartão Chaves API → Chaves Ativas.

Tens feedback ou queres solicitar melhorias? Diz-nos em roadmap.whalemate.com/roadmap