Creating webhook workflows with the workflow settings wizard

To implement a webhook, you create a workflow that specifies parameters such as the HTTP/S URL, HTTP/S method, and request body template. You can then use this webhook in an automation workflow policy.

  1. In the Turbonomic UI, select Settings from the navigation menu and click Workflows.

    workflows option
  2. Click Create workflow.

    Create workflow option

    To edit an existing webhook instead of creating a new one, click the pencil icon for the webhook that you want to edit.

    Edit workflow option

  3. In the Select connection type panel, click Webhook and then click Next.

    Create webhook option

  4. Define the details for your webhook.

    Define webhook details

    1. Display name: Give your webhook a short descriptive name.

      Description: Optionally, provide a longer description.

      Address: Specify the HTTP/S endpoint for your webhook server.

      HTTP Method: Select the HTTP/S method.

      Validate server certificates: Optionally, deselect to skip server certificate validation (for example, to trust self-signed server certificates).

      Web proxy: Optionally, select to enable a proxy host for your webhook.

      define proxy details

      Specify the proxy type, host, and port. Optionally, specify a username and password to authenticate to the proxy host.

    2. Click Next.

  5. Configure authentication.

    Webhook authentication
    1. You can configure authentication to meet the requirements of your webhook API server. Turbonomic supports None, Basic, and OAuth authentication.

      • None: Bypass authentication.
      • Basic: To configure basic authentication, specify a username and password.

      • OAuth: To configure OAuth authentication, specify a client ID, client secret, and the URL of your authorization server.

    2. Click Next.

  6. Add request headers.

    Specify headers

    1. To add request headers, click Add header. You can specify multiple headers to include in your webhook. If your header includes a secret, you can click the Hide value switch so that it does not appear again after it is entered.

    2. Click Next.

  7. Specify the request body.

    Specify request body details

    The request body template uses keywords to substitute action details when the webhook message request is sent. To verify that the keyword substitution is working as wanted, you can provide an existing action UUID to use an as example.

    1. Media type: Specify a media type for your webhook request body. Choose between text, JSON, or XML.

    2. Payload template: Specify the action DTO variables to include in the webhook payload.

      In the example, the payload template value is $action.details. This variable is a reference to a field in the ActionApiDTO object that represents the current action. Your template can reference any of the fields in this DTO, starting with action as the object name. For example, $action.createTime gives you the time the action was created. For a full listing of the ActionApiDTO object, see API Reference or the API Swagger UI.

      For pre-defined request payload examples, see the Turbonomic Orchestration GitHub repository.

    3. Action UUID: To test your webhook, specify the UUID value for a Turbonomic action. To find a suitable action UUID, complete the following steps:
      1. Select Action from the main navigation menu.

      2. Choose an action from the list and click the corresponding Details button.

        Action details

      3. Click the arrow icon (Specify request body details) to open the action in a new tab.

        Open action in new tab.

      4. Copy the action UUID from the end of the Turbonomic URL.

        Action URL

      Specify this UUID in the Action UUID field for the request body.

    4. Optionally, verify the payload template and test the webhook.

      Verify and test buttons

      • To verify the syntax of your payload template, click Verify template. If the template is valid, a checkmark appears and the request payload is displayed. If the template is not valid, an error message appears.

      • To test the end-to-end configuration of your webhook, click Test webhook. If the configuration is valid and the response that is received from the webhook server is successful, a checkmark appears. If the configuration is not valid, or the webhook server response was not successful, both a plus sign (+) and an error message appear.
    5. When you are satisfied with your webhook configuration, click Create.

  8. Create an Automation Policy that uses the webhook.

    For information about creating policies that use webhook workflows for orchestration, see Automation Workflow.

Reviewing webhook details and validation

After you create a webhook, you can quickly review the configuration details from the main Workflows page.

Click the information icon (i) for the webhook that you want to review.

Review workflow option

A side panel opens that displays details about the webhook. The panel includes tabs for the headers, request body, and any policies that are associated with the webhook.

Review workflow panel

If the webhook is invalid for any reason, the panel shows an INVALID template validation status and provides details about the validation failure.

Invalid workflow panel

Sample webhook application

A webhook workflow sends a message to an application through HTTP/S. You express the message as a template that can include values from the action data in its request body. This template can express text, JSON, or any other format that your application can accept.

You can use webhooks to send messages to various existing applications, including IBM API Connect, Slack, Amazon Web Services, and others.

To deploy a simple example, and to test your webhook templates, implement a node.js server that receives the webhook message and prints the template data. If you install this server on a machine in your network, then you can give its URL in the webhook workflow, and test your response to specific actions.

The following example is a listing for a node.js web server.


let port = 9090;          
const http = require("http");
console.log(`Starting server on port ${port}`);

http.createServer((request, response) => {
    request.setEncoding('utf8');
    console.log('REQUEST METHOD: ', request.method);

    let datStr = '';
    request.on('data', chunk => {datStr = datStr + chunk});
    request.on('end', () => {console.log('End of DATA: ', datStr)})
}).listen(port);

When you run this program, it prints a message to the console to say that it is running, and to identify the port it listens on.

When the server receives a message, it prints the request method, and then prints the message request body, as specified in the workflow's template field.

If you configured an Automation Policy to use this workflow, this server logs a message for each action that Turbonomic runs on an entity within the policy's scope.