Initial release
[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 To use Barker, initialize the `Webhook` object:
7
8 ```
9 from barker import Webhook
10 hook = Webhook()
11 ```
12
13 The `Webhook` object has a number of attributes set by the user:
14
15 1. `url`: the url you want to send the webhook notification
16 2. `data`: the information you want to post in the webhook
17 3. `timeout`: the number of seconds to wait for a server response
18 4. `key`: the hashing key used to verify message data. If not given, it defaults to `BARKER`.
19
20 Additionally, some attributes are set by Barker:
21
22 1. `headers`: custom HTTP headers containing information for message verification (`BARKER_SIGNATURE` and `BARKER_TIMESTAMP`)
23 2. `response`: the response received from the server as a `requests.Response` object
24
25 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. Note that hashing is based on escaped unicode characters.