Skip to content

Webhooks

Jump to bottom
amccook edited this page Aug 23, 2023 · 24 revisions

Overview

  1. Tips & Tricks - Important considerations when implementing webhooks
  2. Examples - A repository of webhook examples for a variety of different platforms
  3. Getting Started - A quick guide on how to setup and implement your first webhook.

Official Documentation

Please reference the official documentation to understand how Turbonomic's webhook functionality works:

Tips & Tricks

  1. Identify what platform you’d like Turbo’s webhook to integrate with. Some questions to think about:
    • Does this platform have an API you can make HTTP requests to? If "no", then Turbo cannot integrate its webhook functionality with that platform.
    • In what format does this platform need to receive information?
    • What kind of authentication do you need? Do you need to use custom headers?
  2. Before integrating with Turbo, test the platform’s API calls using tools like Postman or Advanced Rest Client (ARC)
    • Can you successfully make API calls to the platform?
  3. Begin testing with Turbo
    • Integrate the platform’s API payload into Turbo’s Workflow DTO. This involves escaping characters in the platform’s API payload and can lead to annoying syntactical errors when trying to add to Turbo. Leverage online escaping/unescaping tools. For example, JSON Escape and JSON Unescape Online Tool.
    • Leverage Turbo’s Swagger API for testing:
    • Consider which actions you plan on attaching your workflow to
      • If using your webhook on multiple types of actions, ensure the Action DTO for each action has your specified variables, otherwise your webhook will fail. For example, if your Workflows DTO calls for the “cost” of an action (like for a cloud scale action) $action.stats[0].filters[0].value but your webhook has been applied to on-prem VMs, then your webhook will fail for those VMs since there is no $action.stats[0].filters[0].value in the Action DTO.
    • For advanced uses, review the Apache Velocity documentation for more information. Examples include using a For Loop or If/Else logic.
  4. Implementation in Turbo
    • Create a Policy and select your Workflow (webhook) to be used either during Action Generation, Before Execution, Action Execution, or After Execution.
    • Consider having different webhooks for different action types and different scopes if you plan on referencing unique variables that only exist in certain Action DTOs.

Examples

These webhook examples have been built and maintained by the Turbonomic field organization. Use of these webhooks is unsupported.

Getting Started

A quick guide on how to setup and implement your first webhook.

1. Enabling the Webhook Mediation Probe

Make sure the mediation-webhook pod is running on your Turbonomic deployment.

  1. Modify your deployment. Follow the OVA Deployment instructions or Kubernetes Deployment instructions based on your deployment type.
    • OVA Deployment:
      1. SSH into your Turbonomic instance
      2. Edit the CR file:
        vi /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml
      3. Add the following line to your existing spec section: 
          webhook:
    enabled: true
      4. Save and exit the file
      5. Apply the change:
        kubectl apply -f /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml
    • Kubernetes Deployment:
      1. Edit your running deployment:
        kubectl edit Xl
      2. Add the following line to your existing spec section: 
          webhook:
    enabled: true
      3. Save and exit the file.
  2. Verify the mediation-webhook pod is running and ready:
    kubectl get pods | grep webhook

2. Adding a Webhook

Adding a webhook is done via the Turbonomic API. We'll use Turbonomic's Swagger API interface to add the webhook.

  1. Navigate to the Swagger interface: https://<YOUR_TURBO_URL>/swagger or https://<YOUR_TURBO_URL>/apidoc
  2. Expand the Workflows section and locate POST /workflows. Click Try It Out
  3. Paste your webhook payload in the Body section. See the Examples section to use pre-defined webhook payload examples for different platforms.
    • For quick testing you can use webhook.site to get a URL endpoint and investigate Turbonomic's action payload (the variables you can reference in your custom webhook).
    • Here's a payload example using webhook.site, you can replace <YOUR_WEBHOOKSITE_URL> with your own. 
      {
    "displayName": "Action Payload To Webhook.site",
    "className": "Workflow",
    "description": "Actions Send to Webhook Endpoint",
    "discoveredBy": {
        "readonly": false
    },
    "type": "WEBHOOK",
    "typeSpecificDetails": {
        "url": "<YOUR_WEBHOOKSITE_URL>",
        "method": "POST",
        "template": "$converter.toJson($action)",
        "authenticationMethod": "NONE",
        "trustSelfSignedCertificates": false,
        "type": "WebhookApiDTO"
    }
}
  4. Click Execute to add the webhook to Turbo. Verify the 200 response.
  5. From the Response Body make note of the uuid for your webhook. You'll use this value to test your webhook in the next section.

3. Testing a Webhook

You can use Turbonomic's Swagger API page (https://<YOUR_TURBO_URL>/swagger) to test your webhook before implementing it on real action execution.

  1. Now that you've created a webhook, on the Swagger API page, expand the Workflows section and locate POST /workflows/{workflow_Uuid}. Click Try It Out
  2. In the workflow_Uuid box, enter the UUID of the webhook you created in the previous section.
  3. Now we need the UUID of a Turbonomic action to test the webhook. One way to do this is to use your web browser's Developer Tools and open the Action Center in Turbonomic. This will allow you see the Action API call response which contains UUIDs for Turbonomic's pending actions.
    1. In a new browser tab, navigate to the Turbonomic web interface.
    2. While on this page, open your web browser's Developer Tools > Navigate to the Network section
    3. In the Turbonomic interface, navigate to any window that shows the Pending Actions widget. Click the widget's Show All button.
    4. In the Developer Tools > Network window, notice an actions API call is made. Click on it and open its Preview tab.
    5. You'll see a list of actions - the same actions that are visible in the Turbonomic interface. Expand one of the actions. Record its actionID.
  4. Back on the Swagger page, in the body section, replace <YOUR_ACTION_ID> with the actionID you recorded above. Click Execute. 
    {
  "operation": "TEST",
  "actionId": <YOUR_ACTION_ID>
}
  5. Scroll down to the Response Body section and verify you received the following response: 
    {
  "succeeded": true,
  "details": "The call to webhook endpoint was successful."
}
  6. Your webhook has been successfully triggered! If you were using the webhook.site webhook as an example, you can see Turbonomic successfully sent the action payload and it was received. You can now see all the action details that can be referenced in your custom webhook integration.

4. Attaching a Webhook to a Policy

Now that you've created a webhook and verified it executes properly, create an Automation Policy and attach your webhook to it.

  1. In the Turbonomic web interface, go to Settings > Policies
  2. Click on New Policy
  3. Select Automation Policy
  4. In this example, we'll select Virtual Machine. You can integrate a webhook into any automation policy for any entity type.
  5. Provide a name for your policy. Example: VM Resize with Webhook
  6. In the Scope section, click on Select Group of Virtual Machines to specify which VMs should have this policy applied to them.
  7. Select an existing Group or click New Group to create something new. Click Select when done.
  8. Once you've selected your Scope, expand Automation and Orchestration and click on Add Action
  9. In action type select the actions you'd like to associate with your webhook. In this example, we'll select VCPU-Resize-Up, VCPU-Resize-Down, VMEM-RESIZE-UP, VMEM-RESIZE-DOWN
  10. We'll leave the Action Acceptance set to Manual. In this example, we'll tell our webhook to trigger After Execution of an action. Expand the drop down for After Execution and select Notify action workflow.
  11. Click Select Workflow
  12. You'll see the list of workflows (ie Webhooks) that you've created. In this example, we'll select the webhook we created in the previous section. Click the check box of the workflow and click Save.
  13. Click Submit
  14. Click Save Policy
  15. Once you've saved the policy, you'll need to wait ~10 minutes for Turbonomic to associate the policy with the scope you selected. To verify once it's done, on the navigation side bar, select Search > Groups > Type the name of the group you used in the Scope of the policy. In my example, that was My VMs. Click on the Group to navigate to its Overview page.
  16. Click on the Policies tab at the top to see if the your policy has been associated with the group. If you don't see it listed, wait a few more minutes and refresh the page.
  17. Now that it's associated, go to the Actions tab. Since the Policy we created is for Virtual Machine VCPU and VMEM resize actions, let's navigate in Action Center to Resize > Virtual Machines
  18. To confirm the webhook will be triggered when we take an action, let's....take an action! Check the checkbox of one of the actions and click Execute.
  19. Once the action is executed, you can see the webhook was triggered to send the action payload to the webhook.site URL. It works!
  20. Now you can reference the real-world examples and start building your own webhooks.

Turbonomic Orchestration Wiki

Webhooks
  1. Overview
  2. Tips & Tricks
  3. Examples
  4. Getting Started
    1. Enabling the Webhook Mediation Probe
    2. Adding a Webhook
    3. Testing a Webhook
    4. Attaching a Webhook to a Policy
Slack
  1. Slack Overview
  2. Prerequisites
  3. Tips & Tricks
  4. Examples
SendGrid
  1. SendGrid Overview
  2. Prerequisites
  3. Examples
Telegram
  1. Telegram Overview
  2. Tips & Tricks
  3. Examples
Clone this wiki locally