Webhooks
Last updated
Last updated
Ever since Gophish was launched, we've had the ability to fetch campaign results via the API. But sometimes, you may want to have campaign updates pushed directly to you as they happen.
To solve this problem, as of v0.9.0 we've added support for webhooks.
When you configure a webhook, Gophish will make (optionally signed) HTTP requests to an endpoint you control. These requests include the JSON body of the event that just happened- the exact same JSON that you would normally receive via the API. This gives you real-time updates to your campaign as they happen.
Gophish supports multiple webhooks. Only users with the Admin role are able to create webhooks by navigating to the "Webhooks" sidebar entry and clicking the "New Webhook" button.
This signature is sent in the X-Gophish-Signature header, which looks like this:
It's highly recommended to both set a secure secret as well as validating webhook signatures to ensure that events came from your Gophish instance.
Each event has the following format:
The following message values are supported:
Message
Description
Error Sending Email
Gophish was unable to send the email to the recipient
Email Sent
The email was successfully sent to the recipient
Email Opened
The recipient opened the email
Clicked Link
The recipient clicked the link in the email
Submitted Data
The recipient submitted data to the landing page
Email Reported
The "Email Opened", "Clicked Link", and "Submitted Data" events also include the details field which has the following format:
In this example, the foo field is data that was submitted to the landing page. Each form element will have its own key and list of values which will depend on the format of your landing page.
Each webhook sent by Gophish is signed using an optional secret. This signature is computed over the entire request JSON body using the HMAC-SHA256 hashing algorithm. This is a common practiced used elsewhere by organizations like , , , and more.
The recipient the campaign email 🎉
For an example on how to receive, validate, and parse webhook messages from Gophish, we've open-sourced an you can find . However, since we follow the same common signing pattern used by other webhook providers, most libraries should work with Gophish as well.
