Adding AR System webhook to receive automatic notifications

• 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.
• If you rename the form, the webhook is automatically updated with the new name.
• If you copy the form, the webhook is not copied.
• If you delete the form, the webhook is deleted.

Back to top

Before you begin

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 Systemwebhook form or a REST API to register a webhook:

• Registering the AR System webhook by using AR System REST API
• Registering an AR System webhook by using the AR System webhook form

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 parameters in the REST call:

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

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

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

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.

Back to top

Operations supported by the AR System webhook

You can perform the following operations with AR System webhook:

• PUT (Update an existing webhook definition)
• GET (View an existing webhook definition)
• DELETE (Delete/unregister an existing webhook definition)

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, specify the following information: 

Refer to the sample JSON returned by the AR System server:

Back to top

Update a webhook

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

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

Back to top

 Delete a webhook

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

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

Back to top

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 name	Description
  Access Key	The 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 the IMS server authentication user interface.
  Tenant ID	The Tenant ID for which the API keys are generated. The Tenant ID is available in the User Profile section of IMS server.
  Authentication Base URL	Base authentication URL. For example: "https://bmcitsm-adeintqa1-trial.qa.sps.secops.bmc.com"
  Authentication Refresh Token Path	A part of Refresh Token URL, related to the base URL. For example: "/ims/api/v1/auth/tokens"
  Access Secret Key	Access 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 Path	A part of authentication URL, related to base URL. For example: "/ims/api/v1/access_keys/login"

Back to top

The AR System webhook callback response

When the event for which the webhook is registered occurs and the database is updated, 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.

For a 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 callback JSON response is as follows: 

Webhook callback response for an update event

• For an update event, if the webhook registration contains payload fields, then only the fields, which 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 always return 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 SystemWebhook Registration form to return values from all fields on a form.
  

• Use the following code syntax when you want 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 the callback JSON response 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:

Back to top

Sending attachment data in webhook response

When you register a webhook for attachment data, the AR System enters the attachment field value in the Webhook Pending Attachment form. The following image 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 callback JSON response is as follows:

Back to top

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:

The following image shows the AR System webhook form:

Back to top

Setting the AR System webhook payload size

You can limit the payload size of a few selected webhooks or all webhooks in one of the following ways, ensuring reliable data transmission to external applications.

• Send the data in a zip format to the external application by using Gzip compression.
  This method takes the highest precedence over the Centralized Configuration settings and payload size settings for individual webhooks.
• Truncate the data on selected webhooks by setting the payload size limit in your environment.
  This method takes precedence over the Centralized Configuration settings.
• Truncate the data on all the registered webhooks by configuring the Centralized Configuration settings.
  This method takes the least precedence among the methods listed in this section.

To enable compression of the webhook payload

1. Open the AR System Webhook Registration form by using this URL: http://<AR Server name>:<Port number>/arsys/forms/onbmc-s/AR+System+Webhook/.
2. Select the Use Gzip Compression checkbox.

To set the payload size limit for specific webhooks in your environment

You can set the payload limit for specific webhooks in your environment when you want to truncate the data in certain fields in the AR System form. 

1. Open the AR System Webhook Registration form by using this URL: http://<AR Server name>:<Port number>/arsys/forms/onbmc-s/AR+System+Webhook/.

2. To set the payload limit for specific fields, enter the following information:

   Truncation Requested Fields	Specify valid field IDs, separated by semicolons, for which you want the data to be truncated.
   Max Payload Size (Bytes)	Specify the maximum payload size in bytes.

   These settings take precedence over the Central configuration setting parameters.
   For example, if you configure the centralized configuration setting WEBHOOK-MAX-PAYLOAD-SIZE to 4 KB, but set Max Payload Size (Bytes) to 2KB, the webhook payload is truncated to 2KB for the field IDs specified in the Truncation Requested Fields list.

To set the payload size for all the webhooks in your environment

Set the payload limit for all the webhooks in your environment by adding the following parameters in the Centralized Configuration and setting their values as desired.

The following image shows the Centralized Configuration and settings and their values:

For additional information about the Configuration settings, see Configuration-settings-S-Z.

For information about adding the Centralized Configuration settings, see Updating-configuration-settings-by-using-the-AR-System-Configuration-Generic-UI-form.

Troubleshooting

To troubleshoot issues when sending notifications to the external application, see the guidelines in Troubleshooting-issues-when-sending-notification-to-an-external-application-by-using-AR-System-webhook or create a BMC Support case.