Webhooks

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.

Validating Signatures

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 GitHub, Twitter, Twilio, and more.

This signature is sent in the X-Gophish-Signature header, which looks like this:

POST /webhook HTTP/1.1
Host: localhost:9999
Accept-Encoding: gzip
Content-Length: 226
Content-Type: application/json
User-Agent: Go-http-client/1.1
X-Gophish-Signature: sha256=2be52d4b83eb7f19b0ecc75ebd6441cefea5512443eb18d38a8beb2e7584a66c

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.

Event Format

Each event has the following format:

{
    "email": "[email protected]",
    "time": "2020-01-20T17:33:55.553906Z",
    "message": "Email Opened",
    "details": ""
}

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 recipient reported the campaign email 🎉

The "Email Opened", "Clicked Link", and "Submitted Data" events also include the details field which has the following format:

"payload": {
    "rid": "1234567",
    "browser": {
        "address": "127.0.0.1",
        "user-agent": "Mozilla/5.0 (Macintosh; PPC Mac OS X 10_10_4; rv:1.9.3.20) Gecko/2017-08-09 20:28:42 Firefox/3.8",
    },
    "foo": ["bar"]
}

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.

Example Server

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.