Update README master origin/HEAD origin/master 0.1
authorEthan Nelson <git@ethan-nelson.com>
Sat, 17 Aug 2019 16:38:08 +0000 (09:38 -0700)
committerEthan Nelson <git@ethan-nelson.com>
Sat, 17 Aug 2019 16:53:19 +0000 (09:53 -0700)
README.md

index 181cc96..91519b3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,6 +3,9 @@ Barker
 
 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.
 
 
 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.
 
+Initialization
+--------------
+
 To use Barker, initialize the `Webhook` object:
 
 ```
 To use Barker, initialize the `Webhook` object:
 
 ```
@@ -10,7 +13,7 @@ from barker import Webhook
 hook = Webhook()
 ```
 
 hook = Webhook()
 ```
 
-The `Webhook` object has a number of attributes set by the user:
+The `Webhook` object has a number of attributes set by the user (either in the initialization call or afterwards):
 
 1. `url`: the url you want to send the webhook notification
 2. `data`: the information you want to post in the webhook
 
 1. `url`: the url you want to send the webhook notification
 2. `data`: the information you want to post in the webhook
@@ -22,4 +25,25 @@ Additionally, some attributes are set by Barker:
 1. `headers`: custom HTTP headers containing information for message verification (`BARKER_SIGNATURE` and `BARKER_TIMESTAMP`)
 2. `response`: the response received from the server as a `requests.Response` object
 
 1. `headers`: custom HTTP headers containing information for message verification (`BARKER_SIGNATURE` and `BARKER_TIMESTAMP`)
 2. `response`: the response received from the server as a `requests.Response` object
 
-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.
+Sending
+-------
+
+Once the object is populated with `url` and `data` at a minimum, it can be sent by calling the `send` method:
+
+```
+hook.send()
+print(hook.response)
+```
+
+Receiving
+---------
+
+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.
+
+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).
+
+```
+hash = hmac.new(bytes(hash_key, 'utf-8'))
+hash.update(bytes(";".join((headers['BARKER_TIMESTAMP'], data.decode('utf-8'))), 'utf-8'))
+print(hmac.compare_digest(headers['BARKER_SIGNATURE'], hash.hexdigest()))
+```