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
  • 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"
            }'
 

Create Webhook

POST /webhooks

Create a new webhook based on the entity provided.

Takes:
  • Webhook describing the webhook to be created.
Query Parameters:
NameTypeRequiredDescription
fieldsStringfalseThe fields to be included in the response
Takes:
  • A Webhook describing the callback URL and the conditions for triggering the callback.
  • Retrieves:
  • Webhook representing the new webhook
  • Return Status:
    HTTP Status CodeDescription
    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:
    NameTypeRequiredDescription
    webhookIDStringtrueThe ID of the webhook to delete
    Return Status:
    HTTP Status CodeDescription
    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

    Update Webhook

    PUT /webhooks/{webhookID}/enable

    Re-enable a webhook that was disabled. If the webhook was enabled then this request will be ignored.

    Path Parameters:
    NameTypeRequiredDescription
    webhookIDStringtrueThe ID of the webhook to be enabled
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be included in the response
    Retrieves:
  • Webhook representing the reneabled webhook
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)Any input field is missing or malformed
    404 (Not Found)If the requested webhook does not exist
    403 (Forbidden)If the requesting user is not allowed to update the webhook
    Since: 3.14

    Get Webhook

    GET /webhooks/{webhookID}

    Return the webhook matching the supplied webhookID.

    Path Parameters:
    NameTypeRequiredDescription
    webhookIDStringtrueThe ID of the webhook to return
    Retrieves:
  • A Webhook representing the requested webhook
  • Return Status:
    HTTP Status CodeDescription
    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:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first webhook to be returned
    countIntegerfalseMaximum number of webhooks to be returned
    filterObject[]falseThe filter criteria used to select webhooks
    fieldsStringfalseFields to be returned in the selected webhooks
    Retrieves:
  • Webhook[]
  • Return Status:
    HTTP Status CodeDescription
    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:
    NameTypeRequiredDescription
    webhookIDStringtrueThe ID of the webhook to be updated
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be included in the response
    Takes:
  • A Webhook containing the updated attributes for the specified webhook
  • Retrieves:
  • A Webhook representing the updated webhook
  • Return Status:
    HTTP Status CodeDescription
    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