Skip to content

Commit

Permalink
Update webhook.rst (thinkst#218)
Browse files Browse the repository at this point in the history
  • Loading branch information
stavares843 committed Oct 21, 2022
1 parent 72f278b commit 2c7aee6
Showing 1 changed file with 42 additions and 46 deletions.
88 changes: 42 additions & 46 deletions docs/alerts/webhook.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
HTTP Webhook Alerts
====================

OpenCanary includes a customizable Webhook logging handler to send data to a HTTP endpoint. The handler has a few defaults for a basic configuration, but is flexible enough that it can be customized for advanced usage.
OpenCanary includes a customizable Webhook logging handler to send data to an HTTP endpoint. The handler has a few defaults for a basic configuration but is flexible enough that it can be customized for advanced usage.

The following configuration options are required for this handler:

Expand All @@ -14,86 +14,82 @@ The following configuration options are optional:
* **data** - The data or JSON payload to send. Defaults to {"message": "%(message)s"}.
* See advanced data mapping below
* Note: If sending a JSON payload, be sure to add the correct header (see advanced additional options below)
* **status_code** - The HTTP status code that is expected for a success. Defaults to 200.
* **status_code** - The HTTP status code that is expected for success. Defaults to 200.
* **ignore** - A List of string patterns to ignore and not send. Defaults to None.
* See advanced ignore below
* **(option)** - Any additional options added will be forwarded directly to Python Requests
* See advanced additional options below

Here is a basic configuration:

.. code-block:: json
"handlers": {
"Webhook": {
"class": "opencanary.logger.WebhookHandler",
"url": "http://domain.example.com/path",
"method": "POST",
"data": {"message": "%(message)s"},
"status_code": 200
}
```json
"handlers": {
"Webhook": {
"class": "opencanary.logger.WebhookHandler",
"url": "http://domain.example.com/path",
"method": "POST",
"data": {"message": "%(message)s"},
"status_code": 200
}
}
```

## Advanced Usage

### Advanced Data Mapping

The data payload that is sent to Python Requests can be as complex as your use case needs it to be. In order for the message to be included, the pattern `%(message)s` must be included somewhere, but it's not necessarily required if you just want to use the same message for all alerts.
The data payload that is sent to Python Requests can be as complex as your use case needs it to be. For the message to be included, the pattern `%(message)s` must be included somewhere, but it's not necessarily required if you just want to use the same message for all alerts.

For example, you can move the message to a nested section of the data payload:

.. code-block:: json
"data":{
"title": "OpenCanary Alert",
"data": {
"alert": "%(message)s"
}
```json
"data":{
"title": "OpenCanary Alert",
"data": {
"alert": "%(message)s"
}
}
```

### Advanced Ignore

The ignore option is just a list of strings that will not emit any log message that contains the pattern.

For example, if you use the following ignore list:

.. code-block:: json
"ignore": ["192.0.2."]
```json
"ignore": ["192.0.2."]
```

The following logs will drop:

.. code-block:: json
{"dst_host": "192.0.2.5", "dst_port": ...}
{"src_host": "192.0.2.20", "src_port": ...}
```json
{"dst_host": "192.0.2.5", "dst_port": ...}
{"src_host": "192.0.2.20", "src_port": ...}
```

### Advanced Additional Options

In addition to the options listed above, you can include any extra options that you may need in your HTTP request. These options are directly passed to `requests.request()`. Below I have included a few examples, but for a full list of options please see the [official documentation](https://docs.python-requests.org/en/latest/api/#requests.request).

Add headers:

.. code-block:: json
"headers": {
"Authorization": "Bearer 12345",
"Content-Type": "application/json"
}
```json
"headers": {
"Authorization": "Bearer 12345",
"Content-Type": "application/json"
}
```

> Note: If your data payload needs to be JSON serialized, you must include the `"Content-Type": "application/json"` (case sensitive) header.

Add query parameters. For example to add `?test=yes&redirect=no` you would use:

.. code-block:: json
"params": {
"test": "yes",
"redirect": "no"
}
```json
"params": {
"test": "yes",
"redirect": "no"
}
```
Disable SSL verification

.. code-block:: json
"verify": False
```json
"verify": False
```

0 comments on commit 2c7aee6

Please sign in to comment.