Phishing: GoPhish Campaigns
GET /phishing/campaigns
Lists the tenant's phishing campaigns (max. 100, ordered by createdAt desc).
Query params: status (PhishingCampaignStatus, e.g. DRAFT | ACTIVE | COMPLETED)
POST /phishing/campaigns
Create a new campaign. Requires the tenant to have at least one ADMIN user (used as the creator).
Body:
{
"title": "Campanha Q3 2026",
"description": "Simulação de phishing trimestral",
"template": "office365-login",
"targetCount": 50,
"scheduledAt": "2026-07-10T09:00:00Z",
"targets": [
{ "email": "joao@empresa.pt", "first_name": "João", "last_name": "Silva", "position": "Analista" }
]
}
GET /phishing/campaigns/:id
Details of a campaign (includes the clickCount/reportedCount counters).
PATCH /phishing/campaigns/:id
Update a campaign (title, description, template, targetCount, scheduledAt, targets).
DELETE /phishing/campaigns/:id
Delete a campaign.
POST /phishing/webhook
GoPhish event ingestion endpoint (messages that include clicked, reported or campaign complete, matched by campaign_id to the gophishCampaignId stored in EterShield).
Authentication: HMAC-SHA256 signature in the X-Gophish-Signature: sha256=<hex> header, computed over the raw request body and validated. Fail-closed: if the webhook secret is not configured, or the signature is invalid/missing, it responds 401.
POST /api/v1/phishing/webhook
X-Gophish-Signature: sha256=<hmac-hex>
Content-Type: application/json
[
{ "campaign_id": 42, "message": "Clicked Link", "email": "joao@empresa.pt" }
]
Response:
{ "ok": true, "updated": 1 }
POST /phishing/campaigns/:id/launch
Launches a campaign in GoPhish (creates the target group and the campaign, and activates it).
Authentication: unlike the rest of this section, this endpoint does not use x-api-key: it requires an authenticated browser session with the ADMIN or MANAGER role. It is consumed by the dashboard itself.
Body: { "template": "...", "landingPage": "...", "sendingProfile": "...", "launchDate": "...", "sendByDate": "..." } (launchDate/sendByDate optional). Rate limit: 10/min.
Responses: 409 if the campaign was already launched · 422 if it has no recipients · 502 on a GoPhish error.