Webhooks

Err has a little webserver integrated that can bridge web notifications (webhooks) directly to your plugins.

As usual, here is a cookbook.

Webserver configuration

First you need to configure your webserver :

Do :

!config Webserver

And follow the instructions to configure it (listening IP, PORT, usual stuff).

A simple webhook (good for the straight "application/json" mimetype or flat content)

Now all you need to do for a plugin of yours to listen to a specific URI is to add a @webhook decorator:

plugin.py

from errbot.builtins.webserver import webhook
@webhook
def test(self, incoming_request):
    logging.debug(repr(incoming_request))
    return "OK"

This will listen to POST requests on http://yourserver.com/test/, and return "OK" in the response body.

Note1: if you don't return or return None, the framework will assume an empty 200 response.

Note2: if the incoming request is of mimetype json, the framework will parse it and incoming_request will be the parsed json structure directly

A webhook with a custom URI pattern

plugin.py

from errbot.builtins.webserver import webhook
@webhook(r'/custom_uri/.*/')
def test(self, incoming_request):
    logging.debug(repr(incoming_request))
    return "OK"

Same as above except that everything that matches the pattern of the regular expression r'/custom_uri/.*/' will callback your method.

A webhook for form encoded posts (for example the "application/x-www-form-urlencoded" mimetype)

A good example is the github format that posts a form with a "payload" param.

It is still stupid simple to implement it, you just have to pass a form_param :

github.py

from config import CHATROOM_PRESENCE
from errbot.botplugin import BotPlugin
from errbot.builtins.webserver import webhook

class Github(BotPlugin):
    @webhook(r'/github-notifs/', form_param = 'payload')
    def notification(self, payload):
        self.send(CHATROOM_PRESENCE[0], 'Commit on %s !' % payload['repository']['name'], message_type='groupchat')

Testing a webhook from within err

Get the name of your endpoint with !webstatus

Then you can use !webhook test [endpoint] [post_content]

For example:

!webhook test gh_notifs payload=%7B%22pusher%22%3A%7B%22name%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%2C%22repository%22%3A%7B%22name%22%3A%22test%22%2C%22created_at%22%3A%222012-08-12T16%3A09%3A43-07%3A00%22%2C%22has_wiki%22%3Atrue%2C%22size%22%3A128%2C%22private%22%3Afalse%2C%22watchers%22%3A0%2C%22url%22%3A%22https%3A%2F%2Fgithub.com%2Fgbin%2Ftest%22%2C%22fork%22%3Afalse%2C%22pushed_at%22%3A%222012-08-12T16%3A26%3A35-07%3A00%22%2C%22has_downloads%22%3Atrue%2C%22open_issues%22%3A0%2C%22has_issues%22%3Atrue%2C%22stargazers%22%3A0%2C%22forks%22%3A0%2C%22description%22%3A%22ignore%20this%2C%20this%20is%20for%20testing%20the%20new%20err%20github%20integration%22%2C%22owner%22%3A%7B%22name%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%7D%2C%22forced%22%3Afalse%2C%22after%22%3A%22b3cd9e66e52e4783c1a0b98fbaaad6258669275f%22%2C%22head_commit%22%3A%7B%22added%22%3A%5B%5D%2C%22modified%22%3A%5B%22README.md%22%5D%2C%22timestamp%22%3A%222012-08-12T16%3A24%3A25-07%3A00%22%2C%22removed%22%3A%5B%5D%2C%22author%22%3A%7B%22name%22%3A%22Guillaume%20BINET%22%2C%22username%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%2C%22url%22%3A%22https%3A%2F%2Fgithub.com%2Fgbin%2Ftest%2Fcommit%2Fb3cd9e66e52e4783c1a0b98fbaaad6258669275f%22%2C%22id%22%3A%22b3cd9e66e52e4783c1a0b98fbaaad6258669275f%22%2C%22distinct%22%3Atrue%2C%22message%22%3A%22voila%22%2C%22committer%22%3A%7B%22name%22%3A%22Guillaume%20BINET%22%2C%22username%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%7D%2C%22deleted%22%3Afalse%2C%22commits%22%3A%5B%7B%22added%22%3A%5B%5D%2C%22modified%22%3A%5B%22README.md%22%5D%2C%22timestamp%22%3A%222012-08-12T16%3A24%3A25-07%3A00%22%2C%22removed%22%3A%5B%5D%2C%22author%22%3A%7B%22name%22%3A%22Guillaume%20BINET%22%2C%22username%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%2C%22url%22%3A%22https%3A%2F%2Fgithub.com%2Fgbin%2Ftest%2Fcommit%2Fb3cd9e66e52e4783c1a0b98fbaaad6258669275f%22%2C%22id%22%3A%22b3cd9e66e52e4783c1a0b98fbaaad6258669275f%22%2C%22distinct%22%3Atrue%2C%22message%22%3A%22voila%22%2C%22committer%22%3A%7B%22name%22%3A%22Guillaume%20BINET%22%2C%22username%22%3A%22gbin%22%2C%22email%22%3A%22gbin%40gootz.net%22%7D%7D%5D%2C%22ref%22%3A%22refs%2Fheads%2Fmaster%22%2C%22before%22%3A%2229b1f5e59b7799073b6d792ce76076c200987265%22%2C%22compare%22%3A%22https%3A%2F%2Fgithub.com%2Fgbin%2Ftest%2Fcompare%2F29b1f5e59b77...b3cd9e66e52e%22%2C%22created%22%3Afalse%7D

And it will execute the webhook and serve you a little report about what happened