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

BMC Helix Innovation Studio provides the webhook definition—an HTTP callback mechanism to receive real-time event notifications. Administrators can now register a webhook with BMC Helix Innovation Studio 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 BMC Helix 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 callback a webhook with BMC Helix Innovation Studio and the callback 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 callback is retried three times with incremental duration. If the 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 Helix Single Sign-On.

Webhook callback registration

The following parameters are supported for webhook callback registration:

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

"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"
     }

   "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"	
     }

 "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"
     }

"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"
     }

"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"
     }

Webhook callback deregistration

Webhook definition GET data

Webhook definition data page query

The following parameters are supported for data page query:

Webhook callback enable or disable setting

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