Adding AR System webhook to receive automatic notifications
You can use Remedy AR System REST API to register a webhook definition. 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.
AR System webhook
An external application registers a webhook against an AR 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 form.
The following diagram shows how the AR System webhook works:
- You can create multiple webhooks on a form. A webhook supports create, update, and delete operations.
- The AR System webhook supports all data types that Remedy 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 goes down, an event is created in TSOM, which is then sent to Remedy Service Desk. An incident based on the event information is created in Remedy 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
Consider the following points before you register the AR System webhook:
- You must have AR System administrator privileges.
- You must register the AR System webhook through a REST call. For more information, see Overview of the REST API.
- You must have a valid AR-JWT token. For more information, see Access and authentication for the REST API.
Registering the AR System webhook by using AR 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:
Parameter | Description |
---|---|
Event type | An event for which the external application requests call back (for example, create, update, 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:
For more information about AR REST API authentication, see Access and authentication for the REST API. |
Field list | The 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 method | POST | ||||||||||||||||||||
Headers |
| ||||||||||||||||||||
Request body | JSON format | ||||||||||||||||||||
Returns | A unique webhook ID. | ||||||||||||||||||||
Error codes | If the request is not successful, one of the following error codes is returned:
|
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",
"delete"
],
"callback": {
"url": "http://<serve name>:<port number>/webhook",
"authentication": {
"type": "basic",
"username": "Demo",
"password": "Demo123"
}
},
"payload_fields": ["Description" ,"Impact", "Urgency", "Status"]
}
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 update or delete the webhook definition.
If you want to specify a condition in the AR System webhook, use the string qualification format, supported by the AR 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. The following screenshot shows the AR System Webhook form:
To avoid duplicate registration, this form has a unique index form name, events, and Callback URL.
Warning
To create or update the AR System webhook, use the AR REST API. Do not attempt to create or update a webhook by using the AR System Webhook form.
Operations supported by the AR System webhook
An administrator can use the AR System webhook to perform the following operations:
For more information, see the Operations on 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 |
| ||||||||||||||||||
Parameter | Webhook ID | ||||||||||||||||||
Returns | The webhook specified with unique webhook ID. | ||||||||||||||||||
Error codes | If the request is not successful, one of the following error codes is returned:
For more information, see HTTP status codes. |
Refer to the sample JSON to get a webhook on the HPD:Help Desk form:
{
"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 qualifier | http://Server name:Port number/api/arsys/v1.0/webhook/webhook ID | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP method | PUT | ||||||||||||||||||
Content type | Application/JSON | ||||||||||||||||||
Headers |
| ||||||||||||||||||
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:
For more information, see HTTP status codes. |
Refer to the sample JSON to update a webhook on the HPD:Help Desk form:
{
"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:
URL | http://Server name:Port number/api/arsys/v1.0/webhook/webhook ID | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP method | DELETE | ||||||||||||||||||
Headers |
| ||||||||||||||||||
Returns | No 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:
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
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 GUID (179) 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",
"entry_details" : {
"Submitter": "Demo",
"Status": 0,
"Short Description" : "New Incident"
}
}
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.
Example — When you update an incident with description field and the registration contains payload fields as "submitter", "status" and "short descruption" 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:
{
"webhook_id" : "WBH000000000001",
"entry_event" : "delete",
"form_name" : "HPD:Help Desk",
"entry_id" : "000000000000001"
}
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 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--
Comments
Log in or register to comment.