About Webhooks in CSM
Webhooks process incoming messages triggered by events fired in third-party tools and sent to a CSM endpoint. Incoming data must be valid JSON or XML. You can configure webhook endpoints to use no authentication or basic authentication.
Webhooks Processing
Incoming webhooks are processed by the Cherwell REST API, which:
- Validates that the information passed to it is a valid webhook and that a valid URL is provided.
- Validates that the format type declared in an incoming message header matches the body format. If they do not match, the request is rejected.
- Validates an incoming message does not exceed the webhook limit specified for your system. This limit is set on the Set REST API URL and Webhook Settings dialog. The default size limit is 100,000 characters. For more information, see Set the Base URL for the Cherwell REST API.
- Provides a response code to the sender.
For more information, see Webhook Logging.
Parsing JSON or XML Data
Webhooks use JSON and XML Modifiers configured for One-Step Actions to parse, change, and use data between an external tool and CSM. For JSON, incoming data must be either a valid JSON object or array.
- Use the Update Variables or Stored Values Action
Use this Action to create a variable that declares a data type of JSON, JSON Array, XML, or XML Collection and holds valid string data of the selected data type. Place the Action at the beginning of a One-Step Action to ensure the variable is available to all Actions through the Token menu. For more information, see Define an Update Variables or Stored Values Action.
- Use a Token as a Webhook Value
Create a webhook body token and add JSON or XML Modifiers to parse data as part of a One-Step Action. When you create the first Modifier, select As JSON or As XML to declare the data type. You can then chain Modifiers below that to parse complex data sent to the webhook. For more information, see Webhook Modifier Examples.
Webhooks Authentication
The type of authentication you set for your webhook endpoint depends on the third-party tool from which events are fired.
For example, Amazon Simple Notification Services (SNS) uses basic authentication for webhooks. Other tools, such as Jira Software, can use no authentication.
Using CSM Webhooks with Amazon Web Services (AWS)
CSM can use Amazon Simple Notification Services (SNS) as a webhook provider.
Form example:
https://CSM_User:p%[email protected]/webhookendpoint
Should be encoded as:
https://CSM%5FUser:p%[email protected]/webhookendpoint
You should configure webhook endpoints in CSM before configuring the subscription in Amazon. Endpoints must be in HTTPS format.
When you create a webhook in CSM, select Amazon SNS from the Provider Type drop-down list on the General page of the Webhook dialog. For more information, see Create a Webhook Endpoint.