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, and go to the rest/webhooks subdirectory.

Now start Crossbar:

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:

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:

{
   "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.

{
    "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.