Webhooks

Badour can send notifications of new matches to your own HTTP endpoint. If you create a Webhook recipient and assign it to an alert, we'll send POST requests to the URL you've configured, with the details of any matches for that alert. The content type of the payload will be application/json and it will have the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
    "match": {
        "id": 142,
        "created": 1637166176,
        "alert": {
            "id": 1,
            "name": "Default"
        },
        "type": "post",
        "url": "https://reddit.com/r/test/comments/qw46md/this_is_a_test_post/",
        "site": "reddit",
        "data": {
            "id": "qw46md",
            "title": "This is a test post",
            "subreddit": "test",
            "author": "alexbakker_",
            "permalink": "/r/test/comments/qw46md/this_is_a_test_post/",
            "url": "https://example.com",
            "selftext": "",
            "created_utc": 1637169753
        },
        "hits": [
            {
                "created": 1637166176,
                "keyword": {
                    "id": 4,
                    "pattern": "test",
                    "regex": false
                },
                "field": "title",
                "start": 10,
                "end": 14
            }
        ]
    }
}

The contents of the data field is in same format as the item would have when requested from a site's API (Reddit, in the case of the example payload). Badour typically only stores the fields that it needs to do its analysis, so some fields may be missing.

The start and end fields in the list of hits represent the byte indices at which a hit starts and ends.

Limitations

Badour expects that webhook recipients respond within 10 seconds of receiving a request. If you server takes longer than that, the connection is closed. There is no retry mechanism. If a request fails due to a connection issue or an error response from the receiver, the notification is lost.

Security

When exposing an HTTP endpoint to the internet to receive webhook requests from Badour, you may want to verify that any messages sent to that endpoint actually originate from Badour.

If you set a secret for the recipient, Badour uses it the create MAC (message authentication code) of the request payload. This MAC is included in the headers of each request as X-Badour-MAC. The algorithm used to calculate the MAC is HMAC-SHA256.

The secret should be a random string of characters that is hard to guess. We recommend generating a 128-bit secret as follows: openssl rand -hex 16.

Code examples

Most programming languages include support for HMAC-SHA256 out of the box. If you're not sure where to begin with implementing the MAC check, you can refer to the code examples below.

• Python
• Go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

import hashlib
import hmac
from http import HTTPStatus

from flask import Flask, abort, request

_secret = "abcdefghijklmnopqrstuvwxyz".encode("utf-8")

app = Flask(__name__)


@app.route("/hooks/badour", methods=["POST"])
def hook_badour():
    # read the MAC from the header of the request
    if (mac := request.headers.get("X-Badour-MAC")) is None:
        abort(HTTPStatus.BAD_REQUEST)

    # calculate the MAC that we expect, given the request body that was received
    h = hmac.new(_secret, request.get_data(), hashlib.sha256)
    expected_mac = h.hexdigest()

    # compare the two MACs, and abort if they're not equal
    if not hmac.compare_digest(expected_mac, mac):
        abort(HTTPStatus.BAD_REQUEST)

    # YOUR LOGIC HERE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "io/ioutil"
    "log"
    "net/http"
)

var (
    secret = []byte("abcdefghijklmnopqrstuvwxyz")
)

func main() {
    http.HandleFunc("/hooks/badour", func(w http.ResponseWriter, r *http.Request) {
        if r.Method != "POST" {
            http.Error(w, "error: bad method", http.StatusMethodNotAllowed)
            return
        }

        // read the MAC from the header of the request
        macStr := r.Header.Get("X-Badour-MAC")
        if macStr == "" {
            http.Error(w, "error: mac missing", http.StatusBadRequest)
            return
        }
        macBytes, err := hex.DecodeString(macStr)
        if err != nil {
            http.Error(w, "error: mac malformed", http.StatusBadRequest)
            return
        }

        // use a TeeReader to read the body and run it through the mac calculation simultaneously
        mac := hmac.New(sha256.New, secret)
        tr := io.TeeReader(r.Body, mac)
        body, err := ioutil.ReadAll(tr)
        if err != nil {
            http.Error(w, "error: unable to read body", http.StatusInternalServerError)
            return
        }
        expectedMacBytes := mac.Sum(nil)

        // compare the two MACs, and abort if they're not equal
        if !hmac.Equal(expectedMacBytes, macBytes) {
            http.Error(w, "error: bad mac", http.StatusBadRequest)
            return
        }

        // YOUR LOGIC HERE
        fmt.Println(string(body))
    })
    log.Fatalln(http.ListenAndServe(":8000", nil))
}