Custom Webhook Destination
Configuring a Custom Webhook as an alert destination in your Panther Console

Overview

Destinations are integrations that receive alerts from rules, policies, system health notifications, and rule errors. Panther supports configuring a Custom Webhook as the destination where you will receive alerts.
A Custom Webhook Destination requires only a URL to the service which can accept an HTTP POST request containing a JSON payload. This destination type is designed to allow Panther to communicate with other third-party integrations.

How to set up a Custom Webhook alert destination in Panther

Delivery and Ack

The webhook must accept and acknowledge Panther's POST request with an HTTP status code in the 2XX range. If there were any network failures or non 2XX codes, Panther will attempt to retry the request up to ten (10) times before permanent failure.
The webhook response body will be stored in the delivery status which can be viewed in the Alert Details page.
In the event of a permanent delivery failure, Panther logs and provides workflow continuity by allowing the alert to be manually re-sent by visiting the Alert Details page and viewing the Delivery Status section.

Set up a custom webhook in Panther

  1. 1.
    Log in to the Panther Console.
  2. 2.
    On the left sidebar click Integrations > Alert Destinations.
  3. 3.
    Click Create New.
  4. 4.
    Click Custom Webhook.
  5. 5.
    Fill out the form:
    • Display Name: Add a friendly name to identify your destination.
    • Custom Webhook URL: Enter your Custom Webhook forwarding URL.
      • If you followed the ngrok example earlier in this documentation, you would enter the http or https forwarding URL from the ngrok output.
    • Severity: Select the severity level of alerts to send to this Destination.
    • Alert Types: Select the alert types to send to this Destination.
  6. 6.
    Click Add Destination.
  7. 7.
    On the final page, optionally click Send Test Alert to test the integration using a test payload. When you are finished, click Finish Setup.

Custom Webhook Alert Schema

A Custom Webhook will deliver an alert with the following schema:
1
{
2
"id": string,
3
"createdAt": AWSDateTime,
4
"severity": string,
5
"type": string,
6
"link": string,
7
"title": string,
8
"name": string,
9
"alertId": string,
10
"description": string,
11
"runbook": string,
12
"tags": [string],
13
"version": string
14
}
Copied!
The AWSDateTime scalar type represents a valid extended ISO 8601 DateTime string. In other words, this scalar type accepts datetime strings of the form YYYY-MM-DDThh:mm:ss.sssZ. The field after the seconds field is a nanoseconds field. It can accept between 1 and 9 digits. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). The time zone offset is compulsory for this scalar. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.

Example JSON payload:

1
{
2
"id": "AllLogs.IPMonitoring",
3
"createdAt": "2020-10-13T03:35:24Z",
4
"severity": "INFO",
5
"type": "RULE",
6
"link": "https://runpanther.io/alerts/b90c19e66e160e194a5b3b94ec27fb7c",
7
"title": "New Alert: Suspicious traffic detected from [123.123.123.123]",
8
"name": "Monitor Suspicious IPs",
9
"alertId": "b90c19e66e160e194a5b3b94ec27fb7c",
10
"description": "This rule alerts on any activity outside of our IP address whitelist",
11
"runbook": "",
12
"tags": [
13
"Network Monitoring",
14
"Threat Intel"
15
],
16
"version": "CJm9PiaXV0q8U0JhoFmE6L21ou7e5Ek0"
17
}
Copied!

Custom Webhook example

The following example demonstrates sending Panther alerts to a custom webhook which forwards the payload to a simple Node.js server proxied via Ngrok.
  1. 1.
    Open Command Line.
  2. 2.
    Create an ngrok account, install, and and start the service on port 8081.
  3. 3.
    Install Node.js and paste the following snippet into webhook.js:
    1
    const http = require('http')
    2
    const util = require('util')
    3
    const port = 8081
    4
    5
    const requestHandler = (req, res) => {
    6
    7
    if (req.method === 'POST') {
    8
    let body = '';
    9
    req.on('data', chunk => {
    10
    body += chunk.toString();
    11
    });
    12
    req.on('end', () => {
    13
    console.log(util.inspect(JSON.parse(body), false, null, true));
    14
    res.statusCode = 200; // Must ack the request
    15
    res.end("success"); // (Optional) response body
    16
    });
    17
    }
    18
    }
    19
    20
    const server = http.createServer(requestHandler)
    21
    22
    server.listen(port, (err) => {
    23
    if (err) {
    24
    return console.log('something bad happened', err)
    25
    }
    26
    27
    console.log(`server is listening on ${port}`)
    28
    })
    Copied!
  4. 4.
    Open another terminal and start the Node.js server:
    1
    > node webhook.js
    2
    server is listening on 8081
    Copied!

Additional Information on Destinations

For more information on alert routing order, modifying or deleting destinations, and workflow automation, please see the Panther docs: Destinations.