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:
- Bi-directional commenting between two systems
- 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:
- Open a Command line session and change to a working directory
- Execute the command:
c:\NodeWork>jive-sdk create samplewebhooks
Obviously, your directory name may be different
You should see this output:
The result should be a structure like this:
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:
- Now execute the command:
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:
Our URL Service is listening on port 8090:
Now we can deploy the Tile as an Add-on:
Click the Upload Package Button:
Select your Extension.zip and click Continue:
You should see a successful deployment of the Tile to your Community:
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:
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:
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:
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:
Now you are presented with the permission page proper for the OAuth authorization
This Tile configuration has been programmed to politely thank you for granting permissions and allows you to gracefully close the configuration cycle
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.
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:
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.
After a short delay, the console will report it has received the activity,
refresh the webhooks page and the page will update with your recent activity:
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: