The PhishProof Webhooks feature allows external systems to subscribe to real-time events occurring within PhishProof, enabling automated workflows across different platforms.
How It Works
The core function of a PhishProof webhook is to "emit" events as they happen.
- Trigger: A subscribed event occurs within PhishProof (e.g., a campaign starts or a user clicks a link)
- Dispatch: PhishProof constructs a secure data payload (JSON schema) containing contextual information about the event
- Delivery: The payload is sent via an HTTP POST request to a specific destination URL provided by the user
- Action: The receiving external system parses the payload to trigger automated, secondary actions
| Use Case | Description |
|---|---|
| Automated LMS Enrollment | A common integration involves connecting PhishProof with a Learning Management System (LMS). For example, if a user is phished during an active campaign, the webhook immediately notifies the LMS. The LMS then automatically enrolls that specific user in remedial security awareness training, closing the loop on training vulnerabilities without manual administrator intervention. |
Configuration and Management
The PhishProof User Interface (UI) provides a centralized location for configuring, monitoring, and managing your webhook subscriptions.
Admins can register multiple webhook URLs. This flexibility allows you to route different events to different endpoints or entirely separate applications (e.g., sending campaign alerts to Slack, while routing user interactions to an LMS).
- From within PhishProof, navigate to Settings > Webhooks
- Click Create Webhook in the top right
- Fill out the webhook name and payload URL
To ensure secure data transmission and verify that incoming payloads genuinely originate from PhishProof, you can configure unique authentication headers for each webhook.
- Next to Authentication, select one of the following supported authentication options:
- None
- Secret Keys (HMAC signatures): Used to cryptographically sign the payload
- Basic Authentication: Using a designated username and password configuration
Webhook Configuration Guide: Setting Up Your Authentication
To securely deliver data to your server, our system sends webhooks via HTTP POST requests. To ensure these requests are secure and verified, you must configure your preferred authentication method within your webhook configuration profile.
When our system sends a webhook to your URL, it includes an Authorization header containing the credentials you saved. Your server must read and validate this header to verify that the request genuinely originated from our system.
Please choose one of the three authentication methods below to secure your configuration profile:
1. Secret Key Authentication (Recommended)
This method uses a single, secure token (a "shared secret") provided by you.
How to Configure
Generate a secure, random secret key on your server.
Input and save this key into the SecretKey field in our webhook configuration dashboard.
What Our System Sends
We will automatically prepend Bearer to your key in the header:
Authorization: Bearer YOUR_SAVED_SECRET_KEY
Your Server's Job
Configure your server to inspect incoming requests and verify that the Authorization header contains this exact key.
2. Basic Authentication (Credentials)
This method uses a traditional username and password combination.
How to Configure
Create a dedicated username and password on your system specifically for our webhooks.
Select Basic Authentication in our configuration dashboard and input these credentials.
What Our System Sends
Our system automatically combines the credentials (username:password) and encodes them into a standard Base64 string:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Your Server's Job
Your web server or API gateway will automatically decode this header to verify that the username and password match the credentials you created.
3. No Authentication (NoAuth)
This option disables credential checking at the HTTP header layer.
How to Configure
Select NoAuth in our configuration dashboard.
What Our System Sends
Our system will omit the Authorization header entirely.
⚠️ Important Security Note: Only choose this option for temporary testing, or if your server is already protecting the webhook URL using an alternative method—such as restricting access via IP Whitelisting.
Technical Reference for Developers
When your engineering team builds the endpoint to receive our data, they should configure their system to expect the following technical payload structure:
Webhook URL: [Your Configured URL]
HTTP Method: POST
Headers:
Accept: application/json
Content-Type: application/json
Authorization: (Dynamic based on your saved setting below)
Authorization Header Formats
| If You Selected This Profile: | Your Server Will Receive This Header Format: |
|---|---|
| SecretKey | Authorization: Bearer {your_saved_secretkey} |
| Basic (Credentials) | Authorization: Basic {Base64Encoded(your_username:your_password)} |
| NoAuth | (Header is omitted or empty) |
PhishProof currently supports five primary subscription events, providing granular visibility into campaign progress and user interactions.
- Next to Events, select one of the following supported event types from the dropdown menu:
Description |
Event Name | Trigger Condition |
Example of JSON Payload |
|---|---|---|---|
Campaign Started |
campaign.started | Triggered when a scheduled simulation campaign begins sending emails to target users. |
|
Campaign Closed |
campaign.closed | Triggered when a campaign's data collection window officially ends. |
|
User Phished |
user.phished | Triggered when a user interacts with a phishing simulation (e.g., clicks a link, submits data to a form, opens an attachment, or scans a QR code). |
|
User Reported an Email |
user.phishing_reported | Triggered when a user flags a suspicious email using an endpoint tool like the PhishHook reporting button. |
|
Susceptible User Removed |
user.phished.removed | Triggered when an administrator manually removes a user from the susceptible list within the admin UI. |
|
- Click the toggle to enable your webhook
- Click Save Webhook
Managing Webhooks
From the dedicated webhook list page, administrators have full control over active connections:
- Edit webhook to toggle between Active and Inactive states
- Edit payload URLs, authentication, and subscribed events
- Delete obsolete webhook configurations
System Webhooks
Certain webhooks within the PhishProof ecosystem are classified as System Webhooks. These are reserved for deep, native integrations with core partners, and are provisioned, updated, and managed exclusively via secure back-end APIs. To prevent critical integration failures, these configurations cannot be manually added, modified, or deleted through the standard web UI.