Getting Started > Using Webhooks with the Jive Node SDK

Version 6

    In this Getting Started tutorial, we will use the Jive Node SDK to illustrate the potential of Jive Webhooks.

     

    This tutorial should take 15 minutes.

     

     

    Webhooks Overview

     

    Webhooks are user-defined HTTP callbacks that allow you to be notified when events occur on your Jive server. You can use webhooks to synchronize your content without the need to poll the Jive server. This can be valuable, for example, if you are trying to do bidirectional commenting with another system.

     

    Jive supports two types of webhooks:

    • Content webhooks. These cover events related to content changes. For example, notification when someone comments on a document.
    • System webhooks. These cover events unrelated to content. For example, notification when there are changes to a user profile.

     

    A typical Jive webhooks sequence goes like this:

    webhooks.png

    Each step is described below:

    1. Your service requests access tokens from Jive using OAuth authentication.
    2. Your service then requests webhooks using the provided access token. For example:

      curl -i -u {CLIENT_ID}:{CLIENT_SECRET}

               -X GET "https://sample.jiveon.com/api/core/v3/webhooks"

               -H "Authorization: Bearer {ACCESS_TOKEN}”

               -H "Content-Type: application/json"

               -d'{

                    "events" : "document",

                    "callback": "http://{YOUR_SERVICE_URL}/webhooks",

                    "object" : "https://sample.jiveon.com/api/core/v3/places/1020"

                  }'

               
      In response, your service receives the webhooks ID, among other information:

        "id": "{WEBHOOK_ID}", 

        "resources": { 

          "self": { 

            "allowed": ["GET","PUT","DELETE"], 

            "ref": "http://sample.jiveon.com/api/core/v3/webhooks/{WEBHOOK_ID}"    

          }  

        }, 

        "object": "http://sample.jiveon.com/api/core/v3/places/1020”

        "callback": "http://your.service.com/webhooks

      }

               
    3. A user performs some action on the content that merits a webhook notification.
    4. Jive sends information to the callback URL you previously provided. The below snippet is a sample post for a status update:

      { webhook: 'http://localhost:8080/api/core/v3/webhooks/{WEBHOOK_ID}',

        activity:

        {  content: '<a href="http://sample.jiveon.com/people/admin/status/1013">Hello World!</a>

                   in <a href="http://sample.jiveon.com/groups/test-group>My Test Group</a>',

           title: 'Hello World!',

           jive:

            { imagesCount: 0,

              iconCss: 'jive-icon-med jive-icon-status',

              replyCount: 0,

              objectID: 1013,

              canComment: true,

              collectionUpdated: '2014-05-13T15:57:26.479+0000',

              canLike: true,

              collection: '1464927464-1013',

              objectType: 1464927464 },

           verb: 'jive:created',

           updated: '2014-05-13T15:57:26.479+0000',

           target:

            { id: 'http://sample.jiveon.com/api/core/v3/places/1020',

              summary: ' ',

              updated: '2014-05-13T15:56:23.771+0000',

              image: [Object],

              displayName: 'My Test Group',

              published: '2014-03-13T15:12:58.880+0000',

              objectType: 'jive:group',

              url: 'http://sample.jiveon.com/groups/test-group' },

           provider:

            { displayName: 'Jive',

              objectType: 'jive:instance',

              url: 'http://sample.jiveon.com' },

           actor:

            { id: 'http://sample.jiveon.com/api/core/v3/people/1',

              updated: '2014-05-13T15:37:07.716+0000',

              image: [Object],

              displayName: 'Administrator',

              published: '2014-02-26T23:52:23.001+0000',

              objectType: 'jive:person',

              url: 'http://sample.jiveon.com/people/admin' },

           object:

            { id: 'http://sample.jiveon.com/api/core/v3/contents/1058',

              summary: 'Hello World!',

              updated: '2014-05-13T15:57:26.410+0000',

              displayName: 'Hello World!',

              published: '2014-05-13T15:57:26.410+0000',

              objectType: 'jive:update',

              url: 'http://sample.jiveon.com/people/admin/status/1013' },

           published: '2014-05-13T15:57:26.479+0000',

           url: 'http://sample.jiveon.com/people/admin/status/1013'

        }

      }

               
    5. When you no longer want to receive webhooks, you can unsubscribe.

      DELETE /webhooks/{WEBHOOK_ID}

              

     

    Prerequisites

     

    Before running this tutorial:

    1. Install the Jive Node SDK on your development system. Installation instructions are described at Getting Started > Installing the Jive Node SDK.
    2. You need to be able to install add-ons on the Jive server being used for this tutorial. This will require you to be an administrator, a community manager, or have the sandbox property turned on to enable the installation of add-ons for personal use (property name: jive.extension.sandbox.enabled). Registered developers can use the Jive Developer Sandbox, which has the sandbox property turned on.
    3. Your development system must be accessible to the Jive server. If your system is not accessible to the Jive server (e.g. behind a firewall), consider using a cloud-based IDE for this tutorial.

     

    Instructions

     

    The Jive Node SDK is going to be used just to simplify the initial authentication process between Jive and your service. It produces a tile that you can place on any space you want to watch. Although this example is a little contrived (you wouldn't normally install a tile in a place just so that you can watch it from an external system), it easily illustrates how to register for webhooks related to a place.

     

    To run the webhooks example:

    1. Browse to an empty directory where you want your code for this tutorial to reside.
    2. Create the webhooks example from the Jive Node SDK:
      jive-sdk create example-webhooks
      This creates a project with all the code necessary to run the webhooks example. It includes a tile that you will use to watch a particular place. The Jive Node SDK uses built-in OAuth 2.0 authentication for tile registration.
    3. Update all node package dependencies.
      npm update
    4. Follow instructions for deploying your project at Getting Started > Deploying a Jive Node SDK Project as an Add-On.
    5. Be sure that your Node.js service is properly started, as described in the linked document above.
      node app.js
    6. Now we want to put this special webhooks tile in a place that we want to watch.
      1. Browse to a Place.
      2. Select Settings from the Manage submenu.
        install-tile-1.png
      3. On the right panel, click "Add a tile".
        install-tile-2.png
      4. Select "Watch this place" from the "Other" tile category.
        webhook-watch-this-place.png
      5. Authorize Jive to send information to your service.
        webhook-allow.png
      6. Click Save at the bottom of the Place.
        install-tile-5.png
    7. Now, whenever you perform any activity within that place (e.g. add a status update, create new content, comment on a document, etc.), your service is sent information about this activity. The example snippet below shows information about a newly created discussion.

      {

      webhook: 'http://localhost:8080/api/core/v3/webhooks/1004',

        activity:

         { content: '<a href="http://localhost:8080/people/admin">Administrator</a> created

                     <a href="http://localhost:8080/thread/1031">How do you install the Jive SDK?</a> in

                     <a href="http://localhost:8080/groups/you-guys-are-great">My Test Group</a>',

           title: 'How do you install the Jive SDK?',

           jive:

            { iconCss: 'jive-icon-discussion',

              canReply: true,

              replyCount: 0,

              objectID: 1031,

              collectionUpdated: '2014-05-16T22:15:42.757+0000',

              canLike: true,

              collection: '1-1031',

              question: false,

              objectType: 1 },

           verb: 'jive:created',

           updated: '2014-05-16T22:15:42.757+0000',

           target:

            { id: 'http://localhost:8080/api/core/v3/places/1037',

              summary: ' ',

              updated: '2014-05-16T22:12:25.692+0000',

              image: [Object],

              displayName: 'My Test Group',

              published: '2014-03-13T15:12:58.880+0000',

              objectType: 'jive:group',

              url: 'http://localhost:8080/groups/you-guys-are-great' },

           provider:

            { displayName: 'Jive',

              objectType: 'jive:instance',

              url: 'http://localhost:8080' },

           actor:

            { id: 'http://localhost:8080/api/core/v3/people/1',

              updated: '2014-05-16T22:09:56.662+0000',

              image: [Object],

              displayName: 'Administrator',

              published: '2014-02-26T23:52:23.001+0000',

              objectType: 'jive:person',

              url: 'http://localhost:8080/people/admin' },

           object:

            { id: 'http://localhost:8080/api/core/v3/contents/1060',

              summary: 'Hello. I\'m looking for instructions to install the Jive SDK. Thanks.',

              updated: '2014-05-16T22:15:42.478+0000',

              question: false,

              displayName: 'How do you install the Jive SDK?',

              published: '2014-05-16T22:15:42.478+0000',

              objectType: 'jive:discussion',

              url: 'http://localhost:8080/thread/1031' },

           published: '2014-05-16T22:15:42.757+0000',

           url: 'http://localhost:8080/thread/1031' } }

            

     

    Note that the tile itself will not display any webhook-related information — it is just a quick way to send a message to your integration service about a particular place.

     

     

    For More Information