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-Signatureheader, which looks like this:
POST /webhook HTTP/1.1
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:
"email": "[email protected]",
"message": "Email Opened",
messagevalues are supported:
Error Sending Email
Gophish was unable to send the email to the recipient
The email was successfully sent to the recipient
The recipient opened the email
The recipient clicked the link in the email
The recipient submitted data to the landing page
The "Email Opened", "Clicked Link", and "Submitted Data" events also include the
detailsfield which has the following format:
"user-agent": "Mozilla/5.0 (Macintosh; PPC Mac OS X 10_10_4; rv:220.127.116.11) Gecko/2017-08-09 20:28:42 Firefox/3.8",
In this example, the
foofield 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.
For an example on how to receive, validate, and parse webhook messages from Gophish, we've open-sourced an example server you can find on GitHub. However, since we follow the same common signing pattern used by other webhook providers, most libraries should work with Gophish as well.