Setting up webhook notifications

You can use webhooks to share notifications from Decision Center to the application of your choice.

A webhook is an HTTP custom callback, which you use to send notifications to external applications. A webhook is defined by the three following properties:

Mandatory: A URL that specifies the endpoint where to send the event.
Optional: A data source. If you do not specify one, the default data source is used.
Optional: An authentication token to authenticate to your remote secure server.

You can be notified in real time of the following types of events:

When actions that are related to the decision governance framework happen in Decision Center, for example when a user creates a release, or approves an activity.
When a deployment ends, you are notified of its status: completed, failed, or aborted.
When a user creates or updates a rule or a decision table.

You register webhooks with the Decision Center REST API. Events are sent to the registered endpoints in JSON format. You must set up a server able to handle events and to convert them to a format compatible with the target application. For example, if you want to send notifications to Slack, your server must convert the events sent from Decision Center to a format that is compatible with Slack.

Notifications are asynchronous, which means they are done in the background. They are also disabled during long operations such as importing or deleting projects, or synchronizing or merging branches. They are disabled to avoid sending a big batch of individual notifications.

Diagram showing the mechanism of webhooks in Decision Center — Figure 1. Webhooks mechanism in Decision Center

Configuring your webhooks

The Decision Center REST API provides you with four endpoints to handle webhooks:

PUT /webhook/notify to define one or more URLs where notifications are sent, and optionally provide an authentication token.
GET /webhooks/notify to see the list of URLs getting notifications from this instance of Decision Center.
DELETE /webhooks/{webhookId}/notify to delete a webhook.
POST /webhooks/{webhookId}/notify to update an existing webhook.

For more information, see IBM® ODM Decision Center API.

For more information, see Decision Center REST API

Receiving a webhook notification

The JSON payloads received by the server contain various information about your event. The following data is sent:

Table 1. Information sent by an event
Data	Description
`id`	Unique identifier that is given to an event. You use this ID to find the event in log files.
`version`	Version number of an event. This allows you to identify the version of the event. The version always starts at 1.
`author`	The user that triggered the notification.
`date`	The date when an event was emitted, represented a Java™ date (long value).
`sourcename`	The name of the application that sends the event. This value is always Decision Center.
`sourcelink`	The URL of the Decision Center instance that sends the event.
`type`	The type of event that triggers a webhook, which allows you to filter events. The following types are possible: Rule artifacts `RuleCreated`, when a rule is created. `RuleUpdated`, when a rule is updated. `RuleDeleted`, when a rule is deleted. Decision Governance Framework `ReleaseCreated`, when a release is created. `ReleaseUpdated`, when a release is updated. `ReleaseDeleted`, when a release is deleted. `ActivityCreated`, when an activity is created. `ActivityUpdated`, when an activity is updated. `ActivityDeleted`, when an activity is deleted. Deployment `RuleAppDeployment`, when a RuleApp is deployed. VariableSet `VariablesetCreated`, when a variable set is created `VariablesetUpdated`, when a variable set is updated `VariablesetDeleted`, when a variable set is deleted TestSuite `TestsuiteCreated`, when a test suite is created `TestsuiteUpdated`, when a test suite is updated `TestsuiteDeleted`, when a test suite is deleted Operation `OperationCreated`, when an operation is created `OperationUpdated`, when an operation is updated `OperationDeleted`, when an operation is deleted Ruleflow `RuleflowCreated`, when a ruleflow is created `RuleflowUpdated`, when a ruleflow is updated `RuleflowDeleted`, when a ruleflow is deleted Branch `BranchCreated`, when a nonmanaged branch is created `BranchUpdated`, when a nonmanaged branch is updated `BranchDeleted`, when a nonmanaged branch is deleted Snapshot `SnapshotCreated`, when a snapshot is created `SnapshotUpdated`, when a snapshot is updated `SnapshotDeleted`, when a snapshot is deleted
`content`	An array with information about the artifact associated with the event. For example, if you created a release, you have release details such as the approver’s name, due date, and so on.
Optional: `details`	An array with additional information about the event.
`project`	An array with information about the project associated with the event.
`decisionService`	An array with information about the decision service associated with the event.

Examples

The following example shows an event that is sent when a release is created:

{
    "version": "1.0",
    "id": "f3577511-c33b-4275-a5ef-de177598305b",
    "author": "rtsAdmin",
    "date": 1532519296400,
    "type": "ReleaseCreated",
    "content": [{
        "id": "faa9b2af-e2fe-42a4-9834-bb9cdd607334",
        "internalId": "brm.Release:866:866",
        "name": "New Release",
        "parentId": "7b360d2b-46ca-44c1-a945-fb91b9a0103e",
        "documentation": "",
        "buildMode": null,
        "status": "InProgress",
        "owner": "rtsAdmin",
        "targetDate": "2018-08-07T22:00:00.000Z",
        "approvers": [],
        "initial": false,
        "kind": "Release"
    }],
    "sourceName": "Decision Center",
    "sourceLink": "http://9.145.66.219:8081/decisioncenter?datasource=jdbc%2FilogDataSource",
    "project": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    },
    "decisionService": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    }
}

The following example shows an event that is sent when a change activity is updated. Here, the due date was changed. The details of the change are stored in the detail field.

{
    "version": "1.0",
    "id": "4eef8f4d-7c87-4022-b0aa-28bf88ffdb7f",
    "author": "rtsAdmin",
    "date": 1532519323387,
    "type": "ActivityUpdated",
    "content": [{
        "id": "0eade79c-14e5-4155-8a08-23c7d52a168b",
        "internalId": "brm.ChangeAct:881:881",
        "name": "Spring Activity",
        "parentId": "faa9b2af-e2fe-42a4-9834-bb9cdd607334",
        "documentation": "",
        "buildMode": "ClassicEngine",
        "status": "InProgress",
        "owner": "rtsAdmin",
        "targetDate": "2018-08-06T22:00:00.000Z",
        "approvers": [],
        "authors": [],
        "kind": "ChangeActivity"
    }],
    "details": [{
        "targetURL": "http://9.145.66.219:8081/decisioncenter/t/library#overviewactivity?datasource=jdbc%2FilogDataSource&baselineId=brm.ChangeAct%3A881%3A881",
        "updateType": "UPDATE_DUE_DATE",
        "oldValue": 1533679200000,
        "newValue": 1533592800000
    }],
    "sourceName": "Decision Center",
    "sourceLink": "http://9.145.66.219:8081/decisioncenter?datasource=jdbc%2FilogDataSource",
    "project": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    },
    "decisionService": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    }
}

The following example shows an event that is sent when a RuleApp is deployed:

{
    "version": "1.0",
    "id": "e424a030-4aea-4452-bb5f-7450893a9803",
    "author": "rtsAdmin",
    "date": 1532519935332,
    "type": "RuleAppDeployment",
    "content": [{
        "id": null,
        "internalId": null,
        "name": "Report  2018-07-25_01-58-41-821",
        "status": "COMPLETED",
        "ruleAppName": "autoQuoteRuleApp",
        "messages": {
            "elements": [],
            "totalCount": 0,
            "number": -1,
            "size": 0
        },
        "snapshot": {
            "id": "4758d793-e953-4f11-824f-9e9445cfa02a",
            "internalId": "dsm.DsDeploymentBsln:888:888",
            "name": "Deployment_to_QA_env_2018-07-25T11_58_39Z",
            "parentId": "0eade79c-14e5-4155-8a08-23c7d52a168b",
            "documentation": null,
            "buildMode": "ClassicEngine",
            "kind": "DeploymentSnapshot"
        },
        "servers": [],
        "archive": null
    }],
    "details": [{
        "targetURL": "http://9.145.66.219:8081/decisioncenter/t/library#deploymentreport?id=dsm.DSDeploymentReport%3A1%3A1&datasource=jdbc%2FilogDataSource&baselineId=brm.ChangeAct%3A881%3A881"
    }],
    "sourceName": "Decision Center",
    "sourceLink": "http://9.145.66.219:8081/decisioncenter?datasource=jdbc%2FilogDataSource",
    "project": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    },
    "decisionService": {
        "id": "4d9b5dc7-8a7e-404d-a05d-59023707c7d9",
        "internalId": "brm.RuleProject:229:229",
        "name": "AutoQuote",
        "buildMode": "ClassicEngine"
    }
}