This documentation supports the 19.11 version of BMC Helix Platform. 
To view an earlier version, select 19.08 from the Product version menu.

Registering a webhook with BMC Helix Platform to get real-time event notifications

BMC Helix Platform provides the webhook definition—an HTTP callback mechanism to receive real-time event notifications. Developers can now register a webhook with BMC Helix Platform to receive notifications or data when a record event takes place. The webhook Definition eliminates the manual efforts required to create a rule and saves the time consumed by continuous API polling. For more information, see Example of registering a webhook with BMC Helix Platform.

Supported scenarios for using the webhook definition

  • Tenant-specific—The webhook Definition works only with administrator credentials.
  • Record events—The webhook can be registered only on record definitions that have the Public scope (can be used by all applications or libraries). 
    The webhook calls back to the registering application only when one of the following events occur:
    • Create record 
    • Update record
    • Delete record
  • Authorization and Authentication—Basic Auth, OAuth 2.0, and Remedy Single Sign-On. 
  • Supported actions on webhook Definitions
    • Create webhook Definition (register webhook)
    • Get webhook Definition
    • webhook Definition data page query
    • Enable webhook Definition
    • Disable webhook Definition

Unsupported scenarios for using the webhook definition

  • Migrate—webhooks cannot be migrated from one system to another. You must re-register the webhook on the new system. 
  • Update—After registering the URL, the webhook cannot be modified. You must de-register the URL and register the new URL with the required updates. 

Webhook retry policy

When an application tries to register a webhook with BMC Helix Platform and the registration fails or the webhook cannot get real-time notifications, the platform automatically retries the API callbacks for the following HTTP response status codes:

  • 408 Request Timeout Error
  • 409 Conflict
  • 425 Too Early
  • 429 Too Many Requests
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway timeout

The Webhook registration is retried three times with incremental duration. If the registration call fails after the third time, the corresponding HTTP request payload and response code are saved for processing one last time. 

Webhook authentication with OAuth 2.0

If you are using OAuth 2.0, you must configure your application to get the OAuth2.0 token by using REST API. For more information, see Using authorization REST APIs to consume BMC Remedy Single Sign-On.

Webhook callback registration

Registration URLhttp://servername:portnumber/api/rx/application/webhook/webhookdefinition
HTTP RequestPOST

The following parameters are supported for webhook callback registration:

ParameterValueExample
name
  • Webhook definition name
  • "SampleWebhook"
event
  • Record Definition Name
  • Condition (optional)
  • Comma separated record events—create, update, or delete
  • com.example.taskmanager:Task

  • ${webhookContext.536870913} = \"High\" AND ${webhookContext.4} = $NULL$"

  • "create","update"

callback
  • Target REST point URL and headers
  • http://localhost:8008/api/com.example.taskmanager-lib/webhook/is/recordevent/

payloadFieldIds
  • Comma separated field IDs to be included in the callback payload
  • 2, 7, 8
authentication
  • Callback credentials

(Only for the Update record event)

includeAllFields

  • false (default value)—Only the modified field values are included in the webhook response.
  • true—All field values are included in the webhook response.

  • "includeAllFields": false

When you register for the webhook callback, you can provide the conditions to receive a callback. 

For example, you want to register for the webhook callback only when the service request priority is high and is unassigned. If the Priority field ID is 536870913, and the Assignee field ID is 4, then the condition is ${webhookContext.536870913} = "High" AND  ${webhookContext.4} = $NULL$

Sample code for registration 

{
	"name": "Samplewebhook",
	"event": {
		"resourceType": "com.bmc.arsys.rx.services.webhook.domain.webhookRecordEvent",
		"recordDefinitionName": "com.example.taskmanager:Task",
		"condition": "${webhookContext.536870913} = \"High\" AND  ${webhookContext.4} = $NULL$",
		"recordEvents": ["create", "update"]
	},
	"includeAllFields": false,
	"callback": {
		"url": "http://localhost:8008/api/com.example.taskmanager-lib/webhook/is/recordevent/",
		"headers": {
			"secret": "abc"
		},
		"payloadFieldIds": [2, 7, 8],
		"authentication": {
			"resourceType": "com.bmc.arsys.rx.services.webapi.domain.NativeAuthenticationType",
			"httpHeaders": [{
				"key": "X-Requested-By",
				"value": "XMLHttpRequest"
			}, {
				"key": "Content-Type",
				"value": "application/json"
			}],
			"username": "admin",
			"credentials": "Password"
		}
	}
}

Sample code for the supported authentication and authorization methods

 Sample code to register Webhook with Basic Auth
"authentication": {
      "resourceType" :"com.bmc.arsys.rx.services.webapi.domain.BasicAuthenticationType",
      "httpHeaders": [{"key": "X-Requested-By", "value":"XMLHttpRequest"}, {"key": "Content-Type", "value":"application/json"}],	
      "username": "admin",
      "credentials":"password"
     }


 Sample code to register Webhook with Native Authentication
   "authentication": {
      "resourceType" :"com.bmc.arsys.rx.services.webapi.domain.NativeAuthenticationType",
      "httpHeaders": [{"key": "X-Requested-By", "value":"XMLHttpRequest"}, {"key": "Content-Type", "value":"application/json"}],
      "username": "admin",
      "credentials":"password",
      "loginPath": "login path"	
     }


 Sample code to register Webhook with OAuth 2.0
 "authentication": {
      "resourceType" :"com.bmc.arsys.rx.services.webapi.domain.OAuth2ClientCredentials",
      "httpHeaders": [{"key": "X-Requested-By", "value":"XMLHttpRequest"}, {"key": "Content-Type", "value":"application/json"}],
      "username": "admin",
      "credentials":"password",
      "tokenPath":"token path",
      "redirectUri": "url",
      "tokenFetchMechanism": 0 or 1 /* 0 -> basic auth, 1 -> Form post*/,
      "authServerEndpoint": "auth server end point",
      "accessToken": "token value"
     }


 Sample code to register Webhook with Remedy SSO
"authentication": {
      "resourceType" :"com.bmc.arsys.rx.services.webapi.domain.RSSOAuthenticationType",
      "httpHeaders": [{"key": "X-Requested-By", "value":"XMLHttpRequest"}, {"key": "Content-Type", "value":"application/json"}],
      "loginName": "jonnie@petramco.com",
      "credentials":"password",
      "tokenPath":"token path",
      "authServerEndpoint": "auth server end point",
      "accessToken": "token value"
     }


 Sample code to register Webhook with Remedy Authentication
"authentication": {
      "resourceType" :"com.bmc.arsys.rx.services.webapi.domain.RemedyAuthenticationType",
      "httpHeaders": [{"key": "X-Requested-By", "value":"XMLHttpRequest"}, {"key": "Content-Type", "value":"application/json"}],
      "username": "admin",
      "credentials":"password",
      "loginPath": "auth server end point",
      "accessToken": "token value"
     }


Note

For Remedy Authentication, the access token and username/password are mutually exclusive, that is, if you provide the username/password, then the access token is not needed and vice-versa.

Webhook callback deregistration

De-registration URLhttp://servername:portnumber/api/rx/application/webhook/webhookdefinition/webhook name
HTTP RequestDELETE


Webhook definition GET data

URLhttp://servername:portnumber/api/rx/application/webhook/webhookdefinition/webhook name
HTTP RequestGET


Webhook definition data page query

URLhttp://servername:portnumber/api/rx/application/datapage?dataPageType=com.bmc.arsys.rx.application.webhook.datapage.webhookDefinitionDataPageQuery&pageSize=1
HTTP RequestGET


The following parameters are supported for data page query:

Parameter nameValueExample
name

Comma separated webhook name list

(The server returns only those webhooks in the list)

http://servername:portnumber/api/rx/application/datapage?dataPageType=com.bmc.arsys.rx.application.webhook.datapage.
webhookDefinitionDataPageQuery&name=Samplewebhook1,Samplewebhook2,Samplewebhook3
isEnabled

true or false

(The server returns enabled or disabled webhooks)

http://servername:portnumber/api/rx/application/datapage?dataPageType=com.bmc.arsys.rx.application.webhook.datapage.webhookDefinitionDataPageQuery&isEnabled=true
recordEventComma separated list of supported Record events (create or delete) http://servername:portnumber/api/rx/application/datapage?dataPageType=com.bmc.arsys.rx.application.webhook.datapage.webhookDefinitionDataPageQuery&recordEvent=create,delete
recordDefinitionName

Name of the record definition

(The server returns webhooks registered on a given record definition)

http://servername:portnumber/api/rx/application/datapage?dataPageType=com.bmc.arsys.rx.application.webhook.datapage.webhookDefinitionDataPageQuery&name=com.example.taskmanager;Task


Webhook callback enable or disable setting

URLhttp://servername:portnumber/api/rx/application/webhook/webhookdefinition/webhook name
HTTP RequestPUT


Sample code for enabling or disabling webhook

{ "enabled": true or false }

Data provided to applications after registering the webhook callback

After registering for the webhook callback, the system provides the following data in the real-time event notifications:

Create (Create new record)—All the created field IDs are provided in the webhook callback as shown in the following  example:

{
   "recordEvent" : "create"
   "recordDefinitionName" : "com.example.taskmanager-lib:webhookTest",
   "1": "000000000000001",
   "2": "admin@company.com",
   "379": "AGGAABDUC2YGIAP98OXOP8LLIYZRM6",  
   "7": 0
   "8" : "New Task"
}


Update (Update of record definition)—If the includeAllFields parameter has the default value false, only the updated field IDs are provided in the webhook callback. The field values that are unchanged are displayed as null. If the includeAllFields parameter value is true,then all fields are provided in webhook callback. 

Delete (Record is deleted)—Only record definition name and record definition instance ID is provided in the webhook callback.

Troubleshooting webhook failures

If the application URL, credentials, or headers are incorrect, the webhook connection fails. All connection failures are logged in the server logs. 

After registering the application URL for webhook callback, if the application is undeployed and the record definitions are deleted, the system disables the webhook. You can re-deployed the application so that the system restores the record definitions and enables the webhook. 

If the webhook callback fails after three retry attempts, the HTTP Request payload and response code are saved in the Webhook Callback Fail Data record definition for troubleshooting purposes.

Related topics

Adding rules to validate data or trigger events in a process

Configuring a webhook callback for external applications

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

Comments