Webhooks
Webhooks Service
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 |
|
user_session |
|
user_membership |
|
social_group |
|
webhook |
|
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 priveleges 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, get the authorization code, CLIENT_ID and CLIENT_SECRET provided by Jive
- Exchange the authorization code for an ACCESS_TOKEN
Examples:
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 -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.com/webhooks", "object" : "https://sample.jiveon.com/api/core/v3/places/1020" }'
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 -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" : "user_account,user_session,user_membership", "callback": "http://your.service.com/webhooks" }'
In this example we are creating a webhook on Jive instance https://sample.jiveon.com for monitoring the status of any webhooks.
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" : "webhook", "callback": "http://your.service.com/webhooks" }'
Create Webhook
POST /webhooks
Create a new webhook based on the entity provided.
Takes:
- Webhook describing the webhook to be created.
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | The fields to be included inthe response |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | Any input field is missing or malformed |
409 (Conflict) | A webhook with the specified attributes already exists |
Destroy Webhook
DELETE /webhooks/{webhookID}
Delete the webhook matching the specified ID.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
webhookID | String | true | The ID of the webhook to delete |
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | If any input field is missing or malformed |
403 (Forbidden) | If the requesting user is not allowed to delete the webhook |
404 (Not Found) | If the specified webhook does not exist |
Get Webhook
GET /webhooks/{webhookID}
Return the webhook matching the supplied webhookID.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
webhookID | String | true | The ID of the webhook to return |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | Any input field is missing or malformed |
403 (Forbidden) | If the requesting user is not allowed to view the webhook |
404 (Not Found) | If the requested webhook does not exist |
Get Webhooks
GET /webhooks
Return a paginated list of Webhooks owned by the requesting user.
This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.
Filter | Params | Example |
---|---|---|
object | URI of the parent container (eg. groups) to filter events for, or the specific jive content object. | ?filter=object(https://sample.jiveon.com/api/core/v3/places/1020) |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
startIndex | Integer | false | Zero-relative index of the first webhook to be returned |
count | Integer | false | Maximum number of webhooks to be returned |
filter | Object[] | false | The filter criteria used to select webhooks |
fields | String | false | Fields to be returned in the selected webhooks |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | An input field is malformed |
403 (Forbidden) | The requesting user is not allowed to access webhooks |
Update Webhook
PUT /webhooks/{webhookID}
Updates an existing webhook matching the supplied ID.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
webhookID | String | true | The ID of the webhook to be updated |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | The fields to be included in the response |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | Any input field is missing or malformed |
409 (Conflict) | A webhook with the specified attributes already exists |
403 (Forbidden) | If the requesting user is not allowed to update the webhook |