SOC Webhook Integration

PhishNet can push real-time quarantine events to your SIEM, SOAR, or SOC tooling via webhook. Every time an email is quarantined or restored, PhishNet fires an HTTP POST to your registered endpoint.

Registering an endpoint

1. Go to the PhishNet admin dashboard and open Integrations → Webhooks.
2. Click Add endpoint and enter your endpoint URL.
3. Select which events you want to receive.
4. Click Save. A signing secret is displayed — copy it now. It will not be shown again.

Store the signing secret in your secrets manager. You'll use it to verify that webhook deliveries are genuinely from PhishNet.

Event types

Event	When fired
email.quarantined	An email was quarantined — either automatically by policy, or manually by a user
email.restored	A quarantined email was marked safe by a user

Payload

Every delivery is an HTTP POST to your endpoint with Content-Type: application/json.

Envelope

All events share this outer envelope:

{
  "event": "email.quarantined",
  "emitted_at": "2026-05-08T14:30:45Z",
  "event_ref": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {}
}

Field	Type	Description
event	string	Event type (email.quarantined or email.restored)
emitted_at	RFC3339	UTC timestamp when the event was dispatched
event_ref	UUID	Always equals scan_id inside data. Provided in the envelope so consumers can deduplicate before deserializing the full payload.
data	object	Event-specific fields (see below)

email.quarantined and email.restored data

{
  "scan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message_id": "<CABc123@mail.gmail.com>",
  "sender_email": "attacker@example.com",
  "sender_domain": "example.com",
  "sender_display": "IT Support",
  "subject": "Urgent: reset your password now",
  "phish_score": 95,
  "source": "auto",
  "reason": "policy"
}

Field	Type	Description
scan_id	UUID	Unique identifier for this scan
message_id	string	Original Gmail message ID
sender_email	string	Sender's email address
sender_domain	string	Sender's domain
sender_display	string	Sender's display name as shown in Gmail
subject	string	Email subject line
phish_score	integer	Threat score 0–100
source	string	"auto" (triggered by policy) or "manual" (user action)
reason	string	Why the action occurred. For email.quarantined: "policy" (org policy triggered it), "user_override" (user reported it), "user_pref" (user's auto-quarantine setting). For email.restored: "user_restore" (user marked it safe).

HTTP headers

PhishNet sends the following headers with every delivery:

Header	Example	Description
Content-Type	application/json	Always JSON
User-Agent	PhishNet-Webhook/1.0	Identifies the sender
X-Phishnet-Event	email.quarantined	Event type
X-Phishnet-Delivery	<uuid>	Unique ID for this delivery attempt — use for logging
X-Phishnet-Signature	sha256=abc123…	HMAC-SHA256 signature of the raw request body
X-Phishnet-Timestamp	2026-05-08T14:30:45Z	UTC dispatch time (RFC3339)

Verifying signatures

Every delivery is signed. Always verify the signature before processing the payload.

The X-Phishnet-Signature header contains sha256= followed by the lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with your signing secret.

Verification example (Node.js):

const crypto = require('crypto');

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  if (expected.length !== signatureHeader.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Use crypto.timingSafeEqual (or your language's equivalent constant-time comparison) to prevent timing attacks.

Delivery log

The PhishNet admin dashboard shows your 50 most recent webhook deliveries under Integrations → Webhooks → Deliveries. Each entry shows the event type, delivery status, HTTP response code, and any error message — useful for debugging endpoint issues.

Testing your endpoint

Use the Send test event button in the admin dashboard to fire a test delivery to your endpoint and verify your signature verification logic before going live.