Skip to main content
Sumo Logic

About Webhook Connections

Webhook connections allow you to send Sumo Logic alerts to third-party applications that accept incoming Webhooks. For example, once you set up a Webhook connection in Sumo Logic, and create a scheduled search, then you can send an alert from that scheduled search as a post to a Slack channel, or integrate with third-party systems. In addition to alert, you can include a link directly to a search and even a few search results (depending on the third party tool you're connecting to). There is no limit to the number of results sent via webhook on the Sumo Logic side, but restrictions may exist for your third party.

Along with a fully customizable Webhook connection, you can quickly create webhooks for:

Most services with a REST API should allow you to create a connection using the generic Webhook.

About editing or deleting connections

If a connection is changed, all scheduled searches that link to the connection are changed moving forward. No changes are made to previous searches.

If a connection is deleted, the searches sent to those connections are not deleted. To delete these searches, use the Library.

Setting up Webhook Connections

The first step for integrating Webhooks with Sumo Logic is to configure one or more connections, which are HTTP endpoints that tell Sumo Logic where to send data. You can setup any number of connections, depending on your organization's needs.

To set up a Webhook connection

  1. Go to Manage Data > Settings > Connections (Manage > Connections in the classic UI).
  2. On the Connections page click Add.
  3. Click Webhook.
  4. In the Create Connection dialog, enter the Name of the Connection.
  5. Optional: Enter a Description for the Connection.
  6. Enter the URL for the endpoint. This is generated from the remote system’s API.
  1. OPTIONAL: If the third-party system requires an Authorization Header, enter it here.
  2. For Payload, enter a JSON object in the format required by the target Webhook URL. For details on variables that can be used as parameters within your JSON object, see Webhook Payload Variables, next. 
  1. Click Save.
  2. When you're ready, create a scheduled search to send alerts to this connection.

Webhook Payload Variables

For Scheduled Searches (Logs) and Monitors (Metrics)

  • $SearchName: Name of the saved search or Monitor.
  • $SearchDescription: Description of the saved search or Monitor.
  • $SearchQuery: The query used to run the saved search.
  • $SearchQueryUrl: The URL link to the search or metrics query.
  • $TimeRange: Time range used to run the search or time range that triggered the metrics alert.
  • $FireTime: The start time of the search or time that metrics alert triggered.

For Scheduled Searches (Logs) Only

  • $AggregateResultsJson: JSON object containing search aggregation results.
    Important: A maximum of 200 results for this field can be sent via Webhook.
  • $RawResultsJson: JSON object containing raw messages.
    Important: Only 10 results for this field can be sent via Webhook.
  • $NumRawResults: Number of results returned by the search.
    Important: Only 100 results for this field can be sent via Webhook.

For Monitors (Metrics) Only

  • $AlertThreshold: The condition that triggered the alert (for example, above 90 at least once in the last 5 minutes).
  • $AlertSource: The metric and sourceHost that triggered the alert.
  • $AlertID: The ID of the triggered alert.
  • $AlertStatus: Current status of the time series that triggered (for example, Critical or Warning).

Example Authorization Header

Use the following example to construct an authorization header. (Example from the Wikipedia article, "Basic access authentication".)

The Authorization field is constructed as follows:
The username and password are combined with a single colon.
The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.
The authorization method and a space i.e. "Basic " is then put before the encoded string.
For example, if the user agent uses Aladdin as the username and OpenSesame as the password then the field is formed as follows:

echo -n "Aladdin:OpenSesame" | base64

.. yields a string 'QWxhZGRpbjpPcGVuU2VzYW1l' that is used like so:

(The -n makes sure there's not an extra new line being encoded)

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

So in the Authentication Header field, you would enter: 

Basic QWxhZGRpbjpPcGVuU2VzYW1l

Example payloads - flat and hierarchical

This example payload is flat JSON. 

{ 
    "text": "$SearchName ran over $TimeRange at $FireTime", 
    "raw": "$RawResultsJson",
     "num": "$NumRawResults",
     "agg": "$AggregateResultsJson" 
}

This example payload is hierarchical JSON. 

{ "event_type": "trigger",
    "description": "$SearchDescription",
    "client": "Sumo Logic",
    "client_url": "$SearchQueryUrl",
    "details": {
        "name: $SearchName, time: $TimeRange--$FireTime, num: $NumRawResults, agg: $AggregateResultsJson--raw: $RawResultsJson"
    }
}

Example - payload fields

All variables must be enclosed in quotes to be interpreted as valid JSON. 

Correct example

For this example message,

{
   "thread": "conciergePartitioner-1",
   "user_id": "",
   "user_name": "",
   "web_session": "",
   "Message": "2015-10-27 10:31:15,853 -0700 INFO Partitioned 0 tokens, 2 targets into 773 assignments"
}

the following is the payload configuration. Notice that $RawResultsJson is enclosed in quotes.

{
   "channel": "ops",
   "text": "$RawResultsJson"
}

The following valid JSON is sent in the payload of the POST request.

{"channel": "ops", "text": "{\"thread\":\"conciergePartitioner-1\",\"user\_id\":\"\",\"user\_name\":\"\",\"web\_session\":\"\",\"Message\":\"2015-10-27 10:31:15,853 -0700 INFO Partitioned 0 tokens, 2 targets into 773 assignments\"}

Incorrect example

This example shows incorrect formatting for the same message.

The following is the payload configuration. Notice that $RawResultsJson is not enclosed in quotes and therefore the payload field entry constitutes an invalid JSON as can be verified at sites like jsonlint.com.

{
   "channel": "ops",
   "text": $RawResultsJson
}

The following will be sent in the payload of the POST request. It is not valid JSON because the value for text is not enclosed in quotes.

{"channel": "ops", "text": {\"thread\":\"conciergePartitioner-1\",\"user_id\":\"\",\"user_name\":\"\",\"web_session\":\"\",\"Message\":\"2015-10-27 10:31:15,853 -0700 INFO Partitioned 0 tokens, 2 targets into 773 assignments\"}}

Testing a connection

After configuring the Connection, click Test Connection. If the connection is made, you will see a 200 OK response message.

If the Connection is successful, you'll see a message appearing in the third-party tool. This won't contain any information from the scheduled search, it will just have the text in the payload.