Webhooks can send alerts and related data to various third-party apps. This article provides general information to help you understand Cmd webhooks.

Table of contents:

Conceptual overview
The data
Instructions
Additional resources
  

Conceptual overview

Webhooks use HTTP to send data to servers using HTML POST requests. While POSTs can contain multiple data formats, Cmd’s webhooks exclusively send JSON. You can configure Cmd triggers to send webhooks when they fire, and customize which CQL properties each webhook sends. This article describes the information Cmd needs from you in order to create a new webhook, then gives step-by-step instructions for setting one up.
 

The data

When configuring a custom webhook in Cmd, there are four pieces of data you provide: a name (required), a webhook URL (required), custom JSON (required), and CQL values to send (optional but recommended).


Webhook URLs

In order to receive a webhook, a receiving application provides a URL where it will receive incoming webhook requests. You get these URLs from the recipient apps when you set them up to receive webhooks.

CQL values: the contents of Cmd webhooks

The JSON sent in Cmd webhooks follows the following format (without the newlines, which are included throughout this article for readability): 

{"cmd":"echotest",

"Server_hostname":"example-centos7",

"session_how_connected":"sshd",

"Session_ip":"00.000.000.000",

"session_user":"example-user"}

Each key-value pair represents a CQL property which you’ve chosen to include in the webhook, with its corresponding value.


Custom JSON

You can send data other than CQL values by including it as “custom JSON”, which gets inserted at the beginning of the JSON message. For example, if your webhook without custom JSON looked like this:

{"cmd":"ls -la",
  ”cmd_exec_user”:”test-user”}

...but you then added the following as custom JSON:

 {"text":"High priority trigger event fired!”}

...your webhook would arrive like this:

{"text":"High priority trigger event fired!”,
    "cmd":"ls -la",
    ”cmd_exec_user”:”test-user”}

The one required custom JSON value is the webhook URL. This may seem strange since there is a field for the webhook URL - but the URL that goes in that field is the Cmd webhook forwarder for the recipient app. Our webhook forwarders ensure that each recipient app receives input in the format it expects.
 
These are the forwarder URLs for our supported custom webhook recipients:

xMatters: https://us-central1-cmd-production.cloudfunctions.net/xmatters-forwarder

MS Teams: https://us-central1-cmd-production.cloudfunctions.net/msteams-forwarder 

Slack: https://us-central1-cmd-production.cloudfunctions.net/slack-forwarder

The format for the required custom JSON varies slightly for each recipient app.  

  • xMatters:
{"xmatters_webhook":"[WEBHOOK_URL_HERE]"}
  • MS Teams:
{"Teams_webhook_url":"[WEBHOOK_URL_HERE]"}
  • Slack:
{"webhook_url":"[WEBHOOK_URL_HERE]",
 "channel":"#[SLACK_CHANNEL_NAME_HERE]”}

For more information about each webhook integration, see the integrations section of our help center, or the pages about custom webhook integrations for Slack, xMatters, and MS Teams


Instructions

To get your custom webhooks up and running, you will need to create the webhook at the project level, then configure it as a trigger action.

Note: For more information about adding trigger actions, see Adding new triggers.


Adding a webhook to Cmd

Regardless of how you plan to configure your new webhook, you will need to set it up in your Cmd project settings.

  1. Confirm that you are in the correct project by reviewing the current project's name in the top-right corner of the pageNote: To learn more, see Switching between projects.

  2. In the top-right corner, click the current project's name to open the drop-down menu.

  3. Select Project & app settings.

  4. On the left-hand menu, under 'Project settings', select Integrations preferences.

  5. Select Webhook.

  6. Click Add integration in the top-right corner.

  7. Enter the webhook's name, forwarder URL, custom JSON, and your chosen CQL values (as described above).

Note: For a list of all possible CQL properties to send, see Understanding webhook CQL properties.

  • One option is to create two webhooks: one for high-priority alerts and one for low-priority alerts. If you choose to go this route, you could for example add the following into the 'custom JSON to send' field for each:

        - High priority webhook action:  
          {"text":"High priority trigger event fired! - Please check Cmd"}

        - Low priority webhook action:
          {"text":"Low priority trigger event fired! - Please check Cmd"}

8. To test your new webhook, copy the 'Webhook test command' and run it in a terminal. Your recipient app should receive a webhook with mock alert data.

9. When you’re satisfied with your new webhook, click Save.

Sending webhooks with triggers

To add a webhook action to a new trigger, follow the steps in Adding new triggers. To modify an existing trigger to send a webhook, do the following:

  1. Select Triggers from the menu at the top of the web app.

  2. Locate the trigger you'd like to modify and click the menu icon on the right side of its row.

  3. Select Edit.

  4. In Edit mode, scroll to the ‘Actions’ section and click + Add action.

  5. Select Send custom webhook alert.

  6. If you have more than one custom webhook, select the right one from the drop-down list.

  7. Click Save.


Additional resources

Please send any remaining questions to Cmd support. 

Did this answer your question?