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 these methods to convert valid JSON or XML strings into data that CSM can consume:

  1. 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.

  2. 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.

SNS initiates events by sending an unauthorized request to CSM. The Cherwell REST API sends a 401 response and sets the header to basic authentication. Amazon then resends the message with authentication information. The Amazon URL should include authentication information in this format: https://username:password@webhook_endpoint.

When a webhook is configured for Basic Authentication and uses Amazon SNS as a provider type, certain special characters in the username or password fields must be UTF-8 encoded when the subscription request is performed by Amazon.
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.