Update README
[barker/.git] / README.md
1 Barker
2 ======
3
4 Barker is a python module for notifying other servers using the webhook protocol. Webhooks are a way for a web server to communicate out to another server without direct user interaction. They can be used for notifications or triggers to start other services.
5
6 Initialization
7 --------------
8
9 To use Barker, initialize the `Webhook` object:
10
11 ```
12 from barker import Webhook
13 hook = Webhook()
14 ```
15
16 The `Webhook` object has a number of attributes set by the user (either in the initialization call or afterwards):
17
18 1. `url`: the url you want to send the webhook notification
19 2. `data`: the information you want to post in the webhook
20 3. `timeout`: the number of seconds to wait for a server response
21 4. `key`: the hashing key used to verify message data. If not given, it defaults to `BARKER`.
22
23 Additionally, some attributes are set by Barker:
24
25 1. `headers`: custom HTTP headers containing information for message verification (`BARKER_SIGNATURE` and `BARKER_TIMESTAMP`)
26 2. `response`: the response received from the server as a `requests.Response` object
27
28 Sending
29 -------
30
31 Once the object is populated with `url` and `data` at a minimum, it can be sent by calling the `send` method:
32
33 ```
34 hook.send()
35 print(hook.response)
36 ```
37
38 Receiving
39 ---------
40
41 When a webhook is sent, it will include a signature in a header (`BARKER_SIGNATURE`) that is an HMAC hash of the time the webhook was generated (also a header, `BARKER_TIMESTAMP`) and the data joined by a ";". Local verification ensures the message is both correct and current.
42
43 Here is a snippet of code that can be used to verify message integrity. This assumes you have set the received headers to a `headers` variable, received data to a `data` variable, and hash key provided to the sender to `hash_key` (or the string `'BARKER'` if none supplied).
44
45 ```
46 hash = hmac.new(bytes(hash_key, 'utf-8'))
47 hash.update(bytes(";".join((headers['BARKER_TIMESTAMP'], data.decode('utf-8'))), 'utf-8'))
48 print(hmac.compare_digest(headers['BARKER_SIGNATURE'], hash.hexdigest()))
49 ```