:orphan:

HTTP Bridge Webhook
===================

Introduction
------------

    The *HTTP Webhook* feature is available starting with Crossbar
    **0.11.0**.

The *HTTP Webhook Service* broadcasts incoming HTTP/POST requests on a
fixed WAMP topic.

Webhooks are a method of "push notification" used by services such as
GitHub and BitBucket to notify other services when events have happened
through a simple HTTP POST. The HTTP Webhook Service allows you to
consume these events (providing it is accessible by the external
service) through a WAMP PubSub channel (allowing potentially many things
to occur from one webhook notification).

Try it
------

Clone the `Crossbar.io examples
repository <https://github.com/crossbario/crossbar-examples>`__, and go
to the ``rest/webhooks`` subdirectory.

Now start Crossbar:

.. code:: console

    crossbar start

and open http://localhost:8080 in your browser. Open the JavaScript
console to see events received.

To submit an example webhook via HTTP/POST, you can use
`curl <https://curl.haxx.se/>`__:

.. code:: console

    curl -H "Content-Type: text/plain" \
       -d 'fresh webhooks!' \
       http://127.0.0.1:8080/webhook

Configuration
-------------

The *HTTP Webhook Service* is configured on a path of a Web transport -
here is part of a Crossbar configuration:

.. code:: javascript

    {
       "workers": [
          {
             "type": "router",
             ...
             "transports": [
                {
                   "type": "web",
                   ...
                   "paths": {
                      ...
                      "webhook": {
                         "type": "webhook",
                         "realm": "realm1",
                         "role": "anonymous",
                         "options": {
                             "topic": "com.myapp.topic1",
                             "success_response": ""
                         }
                      }
                   }
                }
             ]
          }
       ]
    }

The service dictionary has the following parameters:

+---------+----------------------------------------------------------------------------------------------------------------------------------------+
| option  | description                                                                                                                            |
+=========+========================================================================================================================================+
| type    | MUST be "webhook" (required)                                                                                                           |
+---------+----------------------------------------------------------------------------------------------------------------------------------------+
| realm   | The realm to which the forwarding session is attached that will inject the submitted events, e.g. "realm1"(required)                   |
+---------+----------------------------------------------------------------------------------------------------------------------------------------+
| role    | The fixed (authentication) role the forwarding session is authenticated as when attaching to the router-realm, e.g. "role1" (required) |
+---------+----------------------------------------------------------------------------------------------------------------------------------------+
| options | A dictionary of options (required, see below).                                                                                         |
+---------+----------------------------------------------------------------------------------------------------------------------------------------+


The ``options`` dictionary has the following configuration parameters:


+-------------------+----------------------------------------------------------------------------------------------------------------+
| option            | description                                                                                                    |
+===================+================================================================================================================+
| topic             | The topic to which the forwarded events will be sent.                                                          |
+-------------------+----------------------------------------------------------------------------------------------------------------+
| post_body_limit   | An integer when present limits the length (in bytes) of a HTTP/POST body that will be accepted.                |
|                   | If the request body exceed this limit, the request is rejected. If 0, accept unlimited length. (default: 0)    |
+-------------------+----------------------------------------------------------------------------------------------------------------+
| success_response  | A string to send as the body in a successful reply (default is OK)                                             |
+-------------------+----------------------------------------------------------------------------------------------------------------+
| error_response    | A string to send as the body in an unsuccessful reply (default is NOT OK)                                      |
+-------------------+----------------------------------------------------------------------------------------------------------------+
| github_secret     | The same secret you told GitHub when creating the WebHook configuration.                                       | 
|                   | A string to send as the body in an unsuccessful reply (default is NOT OK)                                      |
+-------------------+----------------------------------------------------------------------------------------------------------------+

With GitHub
-----------

If you set up Crossbar to have a Webhook service, and make it externally
available, you can configure GitHub to send events to it. Underneath
Settings and "Services & Webhooks", you can add a new webhook, which
just requires the URL of the externally-accessible Webhook service. You
can configure GitHub to send certain events, or all events.

When you have configured it, it will send a 'ping' for you to verify it.
As you have configured the Webhook service, you will recieve a message
similar to this (most of the body cut out for brevity) on the WAMP topic
it was configured with.

.. code:: json

    {
        "body": "{\"zen\":\"Design for failure.\",[...more json...]}",
        "headers": {
            "Content-Length": [
                "6188"
            ],
            "X-Github-Event": [
                "ping"
            ],
            "X-Github-Delivery": [
                "7e87c300-462c-11e5-8008-e7623fda32a6"
            ],
            "Accept": [
                "*/*"
            ],
            "User-Agent": [
                "GitHub-Hookshot/4963429"
            ],
            "Host": [
                "atleastfornow.net:8080"
            ],
            "Content-Type": [
                "application/json"
            ]
        }
    }

The message on the WAMP topic will be a dict containing the body as a
string, and the headers as a dictionary of lists.

You will also see the following in the logs:

::

    2015-08-19T04:44:43+0000 [Router        490] Successfully sent webhook from 192.30.252.34 to com.myapp.topic1

For more information on Webhooks, please see GitHub's `Webhooks
Guide <https://developer.github.com/webhooks/>`__.
