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 a hash signature of the request payload. This hash signature is included in the headers of each request as X-Badour-Signature. The algorithm used to calculate the signature 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 signature check, you can refer to the code examples below.