Webhooks are fundamentally HTTP callbacks. In a nutshell, webhooks allows your system to get notified whenever some state
you are interested in changes in a remote system (eg. Jive), avoiding the need to poll. It's a way to integrate systems
based on the observer pattern, allowing your system to subscribe to events and get callback notifications.
External systems may register for and manage webhooks through this webservice. Jive will invoke an endpoint on
the external system if the conditions for triggering the hook are met. Depending on the events field of the registered
Webhook, Jive will send content or system webhook activity object notifications to the
webhook endpoint.
Content webhooks
Content webhooks are created by registering a webhook which specifies a Jive container (space, group, etc.) to
monitor for content events. These events include lifecycle events and social actions:
- jive:created
- jive:modified
- jive:commented
- jive:replied
- jive:liked
- jive:outcome_set
When these events occur, Jive will create an activity object and send it to the webhook callback. The activity
event type is specified in the verb field of the webhook activity object, which is a standard
V3 activity stream object, described below:
Name |
Data Type |
Description |
object |
Object |
JSON describing the subject of the notification.
|
url |
String |
HTML URI of the subject of the notification
|
content |
String |
Summary of the event -- the subject/title of the object, if available.
Limited to 500 characters.
|
title |
String |
Title of the subject of the notification.
|
actor |
Object |
JSON describing the jive user who performed the activity
|
verb |
String |
Type of the activity. Formatted jive:xxxxx where xxxxx is the activity (commented, created, updated, etc.)
|
jive |
Object |
For content activity, JSON describing the parent of the content object.
|
target |
Object |
JSON describing the container of the content object
|
published |
ISO 8601 Date |
The date and time at which this activity was generated.
|
updated |
ISO 8601 Date |
The date and time at which this activity was most recently updated.
|
provider |
Object |
JSON describing the originating Jive instance |
webhook |
String |
URI of the originating webhook |
System webhooks
System webhooks are different from content webhooks in that they are concerned with events that are not
related to content objects, such as user account events, social group lifecycle events,
and webhook lifecycle events.
System webhooks are created by registering a webhook (1) not specifying any object field, and (2)
specifying one or more of the supported event types in the events fields. Note that you cannot mix content
types with system event types. Shown below are the different types of system events, and the range of values
expected from the activity object verb field.
Event Type |
Activity Verb |
user_account
|
- jive:user_account_created
- jive:user_account_deleted
- jive:user_account_disabled
- jive:user_account_enabled
- jive:user_account_invisible
- jive:user_account_visible
- jive:user_profile_modified
- jive:user_type_modified
|
user_session
|
- jive:user_session_login
- jive:user_session_logout
|
user_membership
|
- jive:user_membership_added
- jive:user_membership_removed
|
social_group
|
- jive:social_group_created
- jive:social_group_renamed
- jive:social_group_deleted
|
stream
|
- jive:stream_config_created
- jive:stream_config_modified
- jive:stream_config_deleted
- jive:stream_association_added
- jive:stream_association_removed
|
webhook
|
- jive:webhook_created
- jive:webhook_deleted
- jive:webhook_enabled
- jive:webhook_disabled
- jive:webhook_marked_buggy
- jive:webhook_marked_not_buggy
|
System webhook activity object fields:
Name |
Data Type |
Description |
verb |
String |
Type of the activity. Formatted jive:xxxxx where xxxxx is the activity (commented, created, updated, etc.)
|
jive |
Object |
JSON describing the objectID and objectType of the webhook subject; if the subject is a container,
the containerID and containerType is provided as well.
|
timestamp |
ISO 8601 Date |
The date and time at which this activity was generated.
|
provider |
Object |
JSON describing the originating Jive instance |
webhook |
String |
URI of the originating webhook |
For Jive Administrators: Webhooks tuning parameters
There are several jive properties which can be modified for the purpose of fine tuning the behavior
of webhooks delivery. These are system properties which you must administer from the Administration console, or
the
JivePropertyService. You must also have administrator
privileges to set these properties.
Property |
Description |
Default Value |
jive.webhooks.consumer.payload_size |
Number of notifications to include in a single callback. |
100 |
jive.webhooks.consumer.callbacks_per_exec |
Number of callbacks to perform each time the task runs. |
3 |
jive.webhooks.timeout.connection.default |
Default timeout (in seconds) to use for establishing a connection. |
15 |
jive.webhooks.timeout.read.default |
Default timeout (in seconds) to use for reading from a connection. |
5 |
jive.webhooks.timeout.connection.max |
Maximum timeout (in seconds) to use for establishing a connection. |
15 |
jive.webhooks.timeout.read.max |
Maximum timeout (in seconds) to use for reading from a connection |
5 |
jive.webhooks.queue.rows.max |
Max number of rows we could have in the queue before we start deleting old queued entries. |
330000 |
Examples
Shown below are examples of creating different types of webhooks. Perequisites:
- Register an addon and get the authorization code provided by Jive
- Exchange the authorization code for an ACCESS_TOKEN
Examples:
Create a content webhook
In this example we are creating a webhook on Jive instance https://sample.jiveon.com watching for any content
events on a social group (https://sample.jiveon.com/api/core/v3/places/1020).
curl -i -X POST "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.com/webhooks",
"object" : "https://sample.jiveon.com/api/core/v3/places/1020"
}'
Create a user system webhook
In this example we are creating a webhook on Jive instance https://sample.jiveon.com watching for user account,
session, and social group membership events.
curl -i -X POST "https://sample.jiveon.com/api/core/v3/webhooks"
-H "Authorization: Bearer <ACCESS_TOKEN>"
-H "Content-Type: application/json"
-d'{
"events" : "user_account,user_session,user_membership",
"callback": "http://your.service.com/webhooks"
}'
Create a webhook system webhook
In this example we are creating a webhook on Jive instance https://sample.jiveon.com for monitoring
the status of any webhooks.
curl -i -X POST "https://sample.jiveon.com/api/core/v3/webhooks"
-H "Authorization: Bearer <ACCESS_TOKEN>"
-H "Content-Type: application/json"
-d'{
"events" : "webhook",
"callback": "http://your.service.com/webhooks"
}'