Webhooks as Add-ons

Version 3

    What is a Webhook?

    Webhooks are user defined HTTP callbacks, where a URL callback is registered to be POSTed to by the trigger.

    They are usually triggered by some event, such as publishing a Document or a reply being posted to a Discussion, when that event occurs the source site makes an HTTP request to the URI configured for the webhook.

    Users can configure them to cause events on one site to invoke behavior on another.

     

    Common use cases:

    Common uses are to trigger:

    1. Bi-directional commenting between two systems
    2. Synchronization of content systems without polling

     

    Create Your First Webhook

    The Jive-SDK provides us with an example Webhook which we will look at in more depth.

     

    Having successfully installed the Jive-SDK, you now have the ability to create a new Webhook example:

     

    1. Open a Command line session and change to a working directory
    2. Execute the command:

    c:\NodeWork>jive-sdk create samplewebhooks

    Obviously, your directory name may be different

     

    You should see this output:

    createwebhooks.jpg

    The result should be a structure like this:

    structure.jpg

    This is a functional Webhook add-on using a Tile to identify the Place we want to monitor. We also have a Service which will be notified of events as they occur in the Place the Tile is deployed into

    This Service will simply provide us with a report in a web page of events it has been notified of.

    We can package up the Tile as an Add-on to provide a Webhook for our Jive Instance.

    We will look at this in a bit more depth later, for the moment, let's deploy it to our Jive instance and look at that integration

    Deploying Your Webhook

     

    In your command prompt and working directory:

    • Execute the command:
    c:\NodeWork>npm update
    • Now execute the command:

    c:\NodeWork>node app.js

     

    This will generate the extension.zip file which will be used for installing the Tile and also start the Express server which provides the callback URL Service:

    packaged.jpg

    Our URL Service is listening on port 8090:

    serverstart.jpg

    Now we can deploy the Tile as an Add-on:

    dropdownmenu.jpg

    Click the Upload Package Button:

    uploadbutton.jpg

     

    Select your Extension.zip and click Continue:

    continuebutton.jpg

    You should see a successful deployment of the Tile to your Community:

    addondeployed.jpg

    Note that the Add-on mechanism automatically detects the types of Add-on being deployed in your extension.zip file.

    As part of the deployment, the service also registers the webhook:

    registeringwebhook.jpg

    This provides the identification of a webhook existing on a specific community

     

    Configuring the example Webhook to listen to events in a place

    In order for this example to work, we are provided with a Tile to deploy into a Purposeful place so that our URL service will be notified of activity events in that place.

     

    First we create a Purposeful Place (we will assume you know how to do this).

    Next we need to add our new Tile to the Activity Page:

    addtile.jpg

    Select the Watch this Place! tile.

    As we want this Tile to automatically POST activity to an external service, we will need to configure the Tile:

    configuretile.jpg

     

    This will trigger an 'OAuth dance' where you will grant the external service permission to have access to your Jive Account (without having to divulge your account credentials)

    Click Grant Access:

    oauthstep1.jpg

    Now you are presented with the permission page proper for the OAuth authorization

    Click Allow:

    oauthstep2.jpg

    This Tile configuration has been programmed to politely thank you for granting permissions and allows you to gracefully close the configuration cycle

    oauthstep3.jpg

    The console reports the information used in the OAuth dance with the handshaking of the Jive community (localhost:8080) and the external URL Service (localhost:8090), with the scope of access being restricted to the one Tile instance we just configured.

    consoleoauthdance.jpg

    Having closed the configuration window, we can then complete the creation of the Group by clicking the Create Group button.

    Our Console will report the registration and creation of the Tile instance:

    consolecreategroup.jpg

    Now our Tile has been successfully deployed and configured, we simply need to create some activity in the Group to test the Webhook

    Go ahead, create a new Status update in the Group and open a new Browser page at http://localhost:8090/webhooks.

    statuupdate.jpg

    After a short delay, the console will report it has received the activity,

    consoleactivity.jpg

    refresh the webhooks page and the page will update with your recent activity:

    webhookswebpage.jpg

    We have successfully created, packaged and deployed the webhooks example provided in the jive-sdk.

     

    Now we should look at the mechanics behind our example Webhook:

     

    <<<Index     Next>>