Anatomy of a Webhook

Version 2

    Structure of the Webhook

    When we create our Tile instance and complete the OAuth dance, saving of the Place triggers a jive.constants.globalEventNames.NEW_INSTANCE event for the Tile in our place.

    If we look at the services.js in the tiles/webhooks/backend folder we can see that we export an event handler for just such an event (line 04 here):

     

    exports.eventHandlers = [
    
        {
            'event': jive.constants.globalEventNames.NEW_INSTANCE,
            'handler' : function(theInstance){
                var webhookCallback = jive.service.serviceURL() + '/webhooks';
                var jiveCommunity = theInstance['jiveCommunity'];
    
                var ticketID = theInstance['config']['ticketID'];
    
                function doWebhook(accessToken) {
                    jive.webhooks.register(
                            jiveCommunity, undefined, theInstance['config']['parent'],
                            webhookCallback, accessToken
                        ).then(function (webhook) {
                            webhook['tileInstanceID'] = theInstance['id'];
    
                            var webhookEntity = webhook['entity'];
                            var webhookToSave = {
                                'object': webhookEntity['object'],
                                'events': webhookEntity['event'],
                                'callback': webhookEntity['callback'],
                                'url': webhookEntity['resources']['self']['ref'],
                                'id': webhookEntity['id'],
                                'tileInstanceID': theInstance['id']
                            };
    
                            jive.webhooks.save(webhookToSave);
                        });
                }
                jive.community.find( { 'jiveCommunity' : jiveCommunity }, true).then( function(community) {
    
                    if ( community && community['oauth'] && community['oauth']['access_token'] ) {
                        doWebhook( community['oauth']['access_token']);
                    } else {
                        jive.service.persistence().find('tokens', {'ticket': ticketID }).then(function (found) {
                            var accessToken = found ? found[0]['accessToken']['access_token'] : undefined;
                            doWebhook( accessToken );
                        });
                    }
                });
    
            }
        }
    
    
    ];
    
    
    

     

    The function defined as part of that definition called doWebhook registers a webhook that will listen for events in the Tile instance's parent place, and associates this tile instance with that webhook:

     

    function doWebhook(accessToken) {
                    jive.webhooks.register(
                            jiveCommunity, undefined, theInstance['config']['parent'],
                            webhookCallback, accessToken
                        ).then(function (webhook) {
                            webhook['tileInstanceID'] = theInstance['id'];
    
                            var webhookEntity = webhook['entity'];
                            var webhookToSave = {
                                'object': webhookEntity['object'],
                                'events': webhookEntity['event'],
                                'callback': webhookEntity['callback'],
                                'url': webhookEntity['resources']['self']['ref'],
                                'id': webhookEntity['id'],
                                'tileInstanceID': theInstance['id']
                            };
    
                            jive.webhooks.save(webhookToSave);
                        });
                }
    
    
    

     

    The variable webhookCallback identifies the service endpoint that we want notified of events (in this case our localhost:8090/webhooks)

     

    We can see the code working and notifications sent in the console and the \services\webhooks\backend\routes\explicit_routes.js defines what we do with those notifications.

    The JSON sent to our registered service endpoint is here:

    consoleactivity.jpg

    The contents of the JSON will obviously change depending upon the event.

     

    Clearly this example is a little contrived, but it demonstrates the use of the registration call from our service to register a webhook and processing the notification.