Skip to main content
Sumo Logic

Set Up Webhook Connections

About WebHooks

A WebHook is an HTTP callback: an HTTP POST that occurs when something happens.  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, 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 an 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 WebHooks you can send from Sumo Logic, but your third party might impose restrictions. In addition, the payload of a WebHook may be restricted by Sumo or the 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.

Setting up WebHook connections

The first step in 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.
  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.
  7. (Optional) If the third-party system requires an Authorization Header, enter it here. For more information, see Example Authorization Header below.
  8. 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, below. 
  1. Click Save.
  2. When you're ready, create a scheduled search to send alerts to this connection.

WebHook payload variables

This section lists variables you can use as parameters in the JSON payload object. Variables must be enclosed by double curly brackets.  

Payload variables for scheduled searches (logs) and monitors (metrics)

You can use the following variables when specifying the payload for a WebHook triggered by log or metric queries.

Variable Description 

 {{SearchName}}

Description of the saved search or Monitor. In the delivered payload, this variable is replaced by the Name you assigned to the search or Monitor when you created it.

 {{SearchDescription}}

Description of the saved search or Monitor. In the delivered payload, this variable is replaced by the Description you assigned to the search or Monitor when you created it.

 {{SearchQuery}}

The query used to run the saved search. In the delivered payload, this variable is replaced by your saved search query or metric query.
 

 {{SearchQueryUrl}}

The URL link to the search or metrics query. In the delivered payload, this is a URL that you can click to run the saved search or metric query.

 {{TimeRange}}

Time range used to run the search or time range that triggered the metrics alert. In the delivered payload, this variable will be replaced by the time range for the log or metric query.

 {{FireTime}}

The start time of the log search or metric query that triggered the notification.

Payload variables for scheduled searches (logs) only

Variable Description 

 {{AggregateResultsJson}}

JSON object containing search aggregation results.

A maximum of 200 aggregate results can be sent via WebHook.

 {{RawResultsJson}}

JSON object containing raw messages.
A maximum of 10 raw messages can be sent via WebHook

 {{NumRawResults}}

Number of results returned by the search.

 {{Results.fieldname}}

The value returned from the search result for the specified field name. This is useful for creating an easy-to-read Slack message based on your query results.

A maximum of 200 results for this field can be sent via WebHook.

A field name must exactly match the field from your search, and must be all lowercase, with no spaces in both the query and in the payload specification. For example, customername and customer_name are valid, but CustomerName, Customer_Name, Customer Name are not.
 
Example use of Results.fieldname variable

Single results—For scheduled searches only returning one row of data

This payload text... Results in this output...
"{{Results.client_ip}} had {{Results.errors}} errors" 70.69.152.165 had 391 errors

Multiple results—For scheduled searches returning multiple rows

This payload... Results in this output
"{{Results.client_ip}} had {{Results.errors}} errors" 70.69.152.165 had 391 errors
17.233.159.60 had 381 errors
169.107.162.237 had 319 errors

Payload variables for monitors (metrics) only

You can use the following variables when specifying the payload for a WebHook triggered by a metric query.

Variable Description
{{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

yielding a string 'QWxhZGRpbjpPcGVuU2VzYW1l' that is used like this:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

So in the Authentication Header field, you would enter: 

Basic QWxhZGRpbjpPcGVuU2VzYW1l

Example payloads 

Flat JSON

This example payload is flat JSON. 

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

Hierarchical JSON

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. 

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\"}

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.

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.