This documentation supports the 19.08 version of BMC Helix Platform. 
To view an earlier version, select 19.05 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, webhook cannot be modified. You must de-register the URL and register the new URL with the required updates. 

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 URL—http://servername:portnumber/api/rx/application/webhook/webhookdefinition

HTTP Request—POST
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"]
    },
    "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 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 Request—DELETE

Webhook definition GET data

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

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 diable 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)—Only updated field IDs are provided in the webhook callback. The fields values that are unchanged are displayed as null. 

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. 

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