Phased rollout

This version of the software is currently available only to early adopter SaaS customers as the first step in our phased rollout. Click here to view an earlier version.

Adding AR System webhook to receive automatic notifications

Use the webhook to send real-time event notifications to external systems from the AR System server. The webhook definition eliminates the manual effort required to create workflows and removes the need for continuous server polling. 

An administrator or a user with Role ID -110 can create and perform CRUD operations on a webhook.


AR System webhook

An external application registers a webhook against an AR System form by using the REST API. The webhook generates an automatic notification when the specified event occurs. An event could be creating, updating, or deleting a record on that AR System form.

The following diagram shows how the AR System webhook works: 

  • You can create multiple webhooks on a form. A webhook supports create, update, merge, and delete operations.  
  • The AR System webhook supports all data types that AR System supports.
  • When you rename the form, the webhook is automatically updated with the new name.
  • When you copy the form, the webhook is not copied.
  • When you delete the form, the webhook is deleted.

Scenario

BMC TrueSight Operation Management (TSOM) monitors multiple devices. It also includes a router that performs a network-traffic-directing function. When a router monitored by TSOM is unavailable, an event is created in TSOM, which is then sent to BMC Helix ITSM: Service Desk. An incident based on the event information is created in BMC Helix ITSM: Service Desk.

To get an automatic update about that incident, TSOM uses BMC Helix Integration Service to get automatic notifications from the AR System server. The following diagram shows the workflow of how an automatic notification is sent:


Prerequisites

Before registering the Webhook, make sure that you have a valid AR-JWT token. For more information, see Access and authentication for the REST API.

Registering the AR System webhook

Use the AR System Webhook form or a REST API to register a webhook.

Registering the AR System webhook by using AR System REST API

An external application uses the webhook REST resource to register the AR System webhook. When you register the AR System webhook, define the following information in the REST call:

ParameterDescription
Event typeAn event for which the external application requests call back (for example, create, update, merge, or delete).
Callback URL information

The URL where the AR System server sends the webhook response. The response includes headers, authentication type, and user name, password. The following authentication methods are supported:

  • No auth
  • Basic
  • Identity Management System (IMS)

For more information about No auth and Basic authentication, see Access and authentication for the REST API.

Field listThe list of fields requested by an external application in a webhook response.

To register the AR System webhook, define the following information:

URL qualifier

http://<Server name:Port number>/api/arsys/v1.0/webhook

HTTP methodPOST
Headers
HeaderValue
AuthorizationAR-JWT Token
Content-TypeApplication/JSON
(Optional) X-AR-Client-TypeClient Type ID
(Optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value—120 seconds

(Optional) X-AR-TR-Core-IdThe core ID in a trace ID
(Optional) X-AR-TR-CounterThe counter in a trace ID
(Optional) X-AR-Trace-IdThe complete trace ID
(Optional) X-AR-TR-Is-Counter-LockedThe lock counter
Request bodyJSON format
ReturnsA unique webhook ID.
Error codes

If the request is not successful, one of the following error codes is returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Webhook does not exist
  • 500 - Internal Server Error
For more information, see HTTP status codes.

Refer to the sample output JSON to register the webhook on the HPD:Help Desk form:

{               
  "description": "testWebhook",               
  "form_name": "HPD:Help Desk",               
  "condition": "'Status' !=\"Closed\"",               
  "entry_events": [               
    "create",               
    "update",  
    "merge",             
    "delete"               
  ],               
  "callback": {               
    "url": "http://<serve name>:<port number>/webhook",               
    "authentication": {                               
    "type": "basic",                               
    "username": "Demo",                               
    "password": "Demo123"               
    }               
  },               
  "payload_fields": ["Description" ,"Impact", "Urgency", "Status"]
}

The following sample code shows using the IMS authentication method to register a webhook by using REST API

{     
    "description": "Test Webhook For IMS",
    "form_name": "User",
    "entry_events": [
        "create",               
        "update",  
        "merge",             
        "delete"  
    ],
    "callback": {
        "url": "http://clm-pun-swhrm3:9090/create",
        "authentication": {
			 "type" :"IMS",
			 "accessKey": "SCLTZ1UG33RA9LTXLGVMR0SWBQI0VY",
			 "accessSecretKey": "tfMaboPDU9TEfQrCTKYi2xDeAOzLkv8ZtZbVdxHAJuKiN3DRjI",
			 "tenantId": "1697761359",
			 "authBaseUrl" : "https://bmcitsm-adeintqa1-trial.qa.sps.secops.bmc.com",
			 "authAccessTokenPath" : "/ims/api/v1/access_keys/login",
			 "authRefreshTokenPath" : "/ims/api/v1/auth/tokens",
			 "authHeaderTokenName": "IMS-JWT"
		}
    }
}

When the POST method is successful, the AR System server generates a unique Webhook ID. You can find the Webhook ID in the location response header. Use the Webhook ID when you want to GET, UPDATE or DELETE webhook through REST API.

If you want to specify a condition in the AR System webhook, use the string qualification format, supported by the AR System filter. For more information, see Building qualifications and expressions.

The AR System server stores the registration details in the AR System Webhook form. You can access the AR System Webhook form through Mid Tier. 

To avoid duplicate registration, this form has a unique index form name, events, and Callback URL.

Operations supported by the AR System webhook

You can perform the following operations with AR System webhook:

For more information, see the Webhook section in the Endpoints in AR REST API topic.

Get webhook details 

To fetch information about an existing AR System webhook, define the following information: 

URL qualifier

http://Server name:Port number/api/arsys/v1.0/webhookID/

HTTP method

GET

Headers
HeaderValue
AuthorizationAR-JWT Token
(Optional) X-AR-Client-Type Client Type ID
(Optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(Optional) X-AR-TimeoutTimeout (in seconds) for REST request
Default value—120 seconds
(Optional) X-AR-TR-Core-IdThe core ID in a trace ID
(Optional) X-AR-TR-CounterThe counter in a trace ID
(Optional) X-AR-Trace-IdThe complete trace ID
(Optional) X-AR-TR-Is-Counter-LockedThe lock counter
ParameterWebhook ID
ReturnsThe webhook specified with unique webhook ID.
Error codes

If the request is not successful, one of the following error codes is returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Webhook does not exist
  • 500 - Internal Server Error

For more information, see HTTP status codes.

Refer to the sample JSON returned by AR System Server:

{   
"webhook_id": "WBH000000000101",   
"description": "AllFieldsWebhook_Updated",   
"form_name": "HPD:Help Desk",   
"condition": "",   
"entry_events": [       
"create", "update"   
],   
"payload_fields": [       
"Description" ,"Impact", "Urgency", "Status" 
],   
"enabled": true,   
"callback": {       
"url": "http://<External application server>:<External application port number>/webhook",       
"authentication": {           
"type": "BASIC",          
"username": "Demo",          
"password": "********"       
}   
},   
"_links": {       
"self": [           
{               
"href": "http://<AR Server name>:<Port number>/api/arsys/v1.0/webhook/WBH000000000101"           
}       
]   
}
}

Update a webhook

To update an existing AR System webhook, define the following information: 

URL qualifierhttp://Server name:Port number/api/arsys/v1.0/webhook/webhook ID
HTTP methodPUT
Content typeApplication/JSON
Headers
HeaderValue
AuthorizationAR-JWT Token
(Optional) X-AR-Client-Type Client Type ID
(Optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(Optional) X-AR-TimeoutTimeout (in seconds) for REST request
Default value—120 seconds
(Optional) X-AR-TR-Core-IdThe core ID in a trace ID
(Optional) X-AR-TR-CounterThe counter in a trace ID
(Optional) X-AR-Trace-IdThe complete trace ID
(Optional) X-AR-TR-Is-Counter-LockedThe lock counter
Returns

HTTP status code 204 indicates a successful update.

Error codes

If the request is not successful, one of the following error codes is returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Webhook does not exist
  • 500 - Internal Server Error

For more information, see HTTP status codes.

Refer to the sample JSON returned by AR System server when you update a webhook:

{   
"webhook_id": "WBH000000000101",   
"description": "AllFieldsWebhook_Updated",   
"form_name": "HPD:Help Desk",   
"condition": "",   
"entry_events": [       
"create", "update"   
],   
"payload_fields": [       
"Description" ,"Impact", "Urgency", "Status" 
],   
"enabled": false,   
"callback": {       
"url": "http://<External application server>:<External application port number>/webhook",       
"authentication": {           
"type": "BASIC",          
"username": "Demo",          
"password": "********"       
}   
},   
"_links": {       
"self": [           
{               
"href": "http://<AR Server name>:<Port number>/api/arsys/v1.0/webhook/WBH000000000101"           
}       
]   
}
}

 Delete a webhook

To delete an existing AR System webhook, define the following information: 

URLhttp://Server name:Port number/api/arsys/v1.0/webhook/webhook ID
HTTP methodDELETE
Headers
HeaderValue
AuthorizationAR-JWT <Token>
(Optional) X-AR-Client-Type Client Type ID
(Optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(Optional) X-AR-TimeoutTimeout (in seconds) for REST request
Default value—120 seconds
(Optional) X-AR-TR-Core-IdThe core ID in a trace ID
(Optional) X-AR-TR-CounterThe counter in a trace ID
(Optional) X-AR-Trace-IdThe complete trace ID
(Optional) X-AR-TR-Is-Counter-LockedThe lock counter
ReturnsNo request body, but HTTP status 204 indicates successful deletion.
Error codes

If the request is not successful, one of the following error codes is returned:

  • 403 - Forbidden
  • 404 - Webhook does not exist
  • 500 - Internal Server Error

For more information, see HTTP status codes.

Refer to the sample JSON to delete a webhook on the HPD:Help Desk form:

http://AR Server name>:<Port number>/api/arsys/v1.0/webhook/WBH000000000101

Registering an AR System webhook by using the AR System Webhook form

The AR System Webhook form provides an interface to register a webhook. The following screenshot shows the AR System Webhook Registration form:


The following authentication options are available for registering a webhook:

  • No authentication
    No authentication details are required to register a webhook.
  • Basic
    Provide user name and password to register a webhook.
  • IMS
    Provide the following details to register a webhook:

    Field nameDescription
    Access KeyThe Access Key of the Identity Management System (IMS) server where you want to consume the webhook. When you generate an access key for an IMS user, select No Expiry in IMS server authentication user interface.
    Tenant IDTenant ID for which the API keys are generated. The Tenant ID is available in the User Profile section of IMS server.
    Authentication Base URLBase Authentication URL. For example:
    "https://bmcitsm-adeintqa1-trial.qa.sps.secops.bmc.com"
    Authentication Refresh Token PathA part of Refresh Token URL, related to the Base URL. For example: "/ims/api/v1/auth/tokens"
    Access Secret KeyAccess Secret key is generated along with the Access Key.
    Authentication Token Header Prefix

    The authorization header for the token that is obtained.

    For example, "IMS-JWT"
    In this example, IMS-JWT is the key string. When you register a webhook, you can configure this string by using the field value.

    Authentication Access Token PathA part of authentication URL, related to Base URL. For example, "/ims/api/v1/access_keys/login"

The AR System webhook callback response

When the event for which the webhook is registered occurs and the database changes are committed, the AR System server invokes the external application on the callback URL. Every webhook callback response contains the Webhook ID, form name, event, entry ID, and entry details. Entry details are not provided for the DELETE operation.

In case of create event, the entry ID is NULL for Join forms. For Join forms, you can use any other field ID, such as ID (379) or any other custom field that gives unique value for a specific record.

Example⁠— When a webhook registration contains payload fields such as submitter, status, and short description, the sample callback JSON response is as follows: 

{
   "webhook_id" : "WBH000000000001",
   "entry_event" : "create",
   "form_name" : "HPD:Help Desk",
   "entry_id" : "000000000000001",
   "record_id":"AGGAA5V0G7LDIAQLFCY6QKGM9CABDM",
   "entry_details" : {
		"Submitter": "Demo",
   		"Status": 0,
   		"Short Description" : "New Incident"
   }  
}

Webhook callback response for an update event

If the webhook registration contains payload fields, then in case of update event, the fields that are updated from the registered field list are returned as an update event callback response. If you do not specify any field, the webhook returns all updated fields.  Webhook ID, recordEvent, formName and Entry ID are returned for a payload.

Optionally choose to return data from all fields or only for the updated fields on the form. You can choose to return data from all fields by using either of the following method:

  • Select the Send Unchanged Fields option on the AR System Webhook Registration form to return values from all fields on a form.
  • Use the following code syntax when you want to return data from all fields.

    {
        "description":
    "SampleWebhook-1",
        "form_name": "User",
        "condition": "",
        "entry_events": [       
    "create",      
    "update"
        ],
        "payload_fields": [
            "Login Name",
            "Full Name",
            "Email Address",
            "License Type"
        ],
        "enabled": true,
        "callback": {
            "url":"https://call-this-server-when-changes-happen-on-user-form/"       
    "authentication": {           
    "type": "NO_AUTH",           
    "username": null,           
    "password": null,           
    "accessKey": null,           
    "accessSecretKey": null,           
    "tenantId": null,           
    "authBaseUrl": null,           
    "authAccessTokenPath": null,           
    "authRefreshTokenPath": null,           
    "authHeaderTokenName": null
            }
        },
        "send_attachment_as_reference":
    false,
        "send_unchanged_fields": true,
        "_links":
    {    
    
    
        }}

Example ⁠— When you update an incident with  description field and the registration contains payload fields as "submitter", "status" and "short description" then sample callback JSON response is as follows: 

{
   "webhook_id" : "WBH000000000001",
   "entry_event" : "update",
   "form_name" : "HPD:Help Desk",
   "entry_id": "000000000000001",
   "entry_details" : {
        "Short Description" : "New Incident"
   }
}

For the delete event

For the delete event, the callback response contains webhookId, recordEvent, formName, and entryId. No other fields are returned. 

The sample callback JSON is as follows:

For the delete event
For the delete event, the callback response contains webhookId, recordEvent, formName, and entryId. No other fields are returned. 
The sample callback JSON is as follows:

Sending attachment data in webhook response

When you register a webhook for attachment data, the AR System server enters the attachment field value in the Webhook Pending Attachment form. The following screenshot shows the Webhook Pending Attachment form:

When the webhook contains one or more attachment fields, the AR System server returns the callback response as a multipart, form-data entity. Each part of the attachment field has a name, a content type, and the value.

The attachment request has two or more parts. The first part contains the entry ID with content type as Application/JSON. The other parts can have information, such as attach-{fieldName} with any content type and any value. 
The name is a prefix that indicates binary data. The part after the hyphen is the name of the attachment field. 

Example⁠—When the webhook registration contains payload fields, such as Submitter, Status, Short Description, Attachment1, and Attachment field, the sample callback JSON response is as follows:

--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
Content-Disposition: form-data; name="entry"
Content-Type: application/json; charset=UTF-8

{
   "webhook_id" : "WBH000000000001",
   "entry_event" : "create",
   "form_name" : "HPD:Help Desk",
   "entry_id" : "000000000000001",
   "entry_details" : {
		"Submitter": "Demo",
   		"Status": 0,
   		"Short Description" : "New Incident"
   }  
}

--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
Content-Disposition: form-data;
name="attach-Attachment1"; filename="sample.png"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

<binary data removed for brevity>
--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB--

Sending custom JSON in webhook response

Use the Custom JSON field on the AR System Webhook form to send additional custom payload to external application in JSON format. An external application can leverage the additional payload as plain data and perform further actions as per the requirements and workflows.

See the sample custom JSON. In this example, external application is receiving instruction on the "action" key and data on the "group_id" key:

{
"action":"AddToLogicalGroup",
"group_id":"AGGAA5V0G7X59AQLD1QCQLD1QCUP1Z"
}

The following screenshot shows the AR System Webhook form:


Was this page helpful? Yes No Submitting... Thank you

Comments