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 set up any number of connections, depending on your organization's needs.

To set up a webhook connection

  1. Go to Manage Data > Alerts > Connections.
  2. On the Connections page click the + button on the top right of the table.
  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. (Optional) Custom Headers, enter up to five comma separated key-value pairs.
  9. 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. 
  10. Click Save.
  11. When you're ready, create a scheduled search to send alerts to this connection.

Webhook payload variables

Variables are used as parameters in the JSON payload object of your alert notifications. These variables are used to dynamically populate specific values from the alert configuration in the notification payload. It includes things like the TriggerType that gives the current monitor status in the notification. When a notification is sent variables are replaced with values from the alert. For example, if you specified {{Name}} in your JSON payload, it would be replaced with the actual name of the alert in the delivered payload.

Common variables for alerts

You can use variables to customize your notification payload from Monitors, Scheduled Searches, and Metrics Monitors. The table below shows a list of variables along with information on which area of the product these are supported. We have also provided a brief description of each of the variables.

Variable Description Monitors Metrics Monitors Scheduled Searches
 {{Name}} The name of the alert. In the delivered payload, this variable is replaced with the Name you assigned to the alert when you created it. Check.png Check.png Check.png
 {{Description}} The description of the alert. Check.png Check.png Check.png
{{MonitorType}} The type of alert, either Logs or Metrics. Check.png Check.png Check.png
 {{Query}} The query used to run the alert. Check.png Check.png Check.png
{{QueryURL}} The URL link to open the query (mentioned above) on the logs or metrics page depending upon MonitorType. Check.png Check.png Check.png
{{ResultsJson}} JSON object containing the query results that triggered the alert.

A maximum of 200 aggregate results or 10 raw messages for this field can be sent via webhook.
Check.png Check.png Check.png
{{ResultsJson.fieldName}}

 
The value of the specified field name. For example, this payload specification:

{{ResultsJson.client_ip}} had {{ResultsJson.errors}} errors

Results in a subject line like this:

70.69.152.165 had 391 errors

A maximum of 200 aggregate results or 10 raw messages for this field can be sent via webhook.

A field name must match (case-insensitive) the field from your search and must be alphanumeric characters, underscores, and spaces. If you have a field name that has an unsupported character use the as operator to rename it.

You can return a specific result by providing an array index value in bracket notation. Such as, {{ResultsJson.fieldName}}[0] to return the first result.

Reserved Fields

The following are reserved field names. They are generated by Sumo Logic during collection or search operations.
  • _raw
  • Message
  • _messagetime
  • Time
  • _sourcehost
  • Host
  • _sourcecategory
  • Category
  • _sourcename
  • Name
  • _collector
  • Collector
  • _timeslice
  • _signature
Check.png

 
Check.png

 
Check.png

 
{{NumQueryResults}} The number of raw results (messages or time-series) the query returned. 

This is the number of raw results; displayed in the Messages tab of the Search page.
Check.png Check.png Check.png
{{Id}} The unique identifier of the monitor or search that triggered the alert. Check.png Check.png Check.png
{{DetectionMethod}} This is the type of Trigger Method used to detect alerts. At this time we only support Static threshold-based alerts. Check.png Check.png Check.png
{{TriggerType}} The status of the alert, either Normal, Critical, Warning, or Missing Data. Check.png Check.png x-sized.png
{{TriggerTimeRange}} The time range of the query that triggered the alert. Check.png Check.png Check.png
{{TriggerTime}} The time the monitor was triggered. Check.png Check.png Check.png
{{TriggerCondition}} The condition that triggered the alert. Check.png Check.png Check.png
{{TriggerValue}} The value that triggered the alert. Check.png Check.png Check.png
{{TriggerTimeStart}} The start time of the time range that triggered the monitor. Check.png Check.png Check.png
{{TriggerTimeEnd}} The end time of the time range that triggered the monitor. Check.png Check.png Check.png
{{SourceURL}} The URL to the configuration or status page of the monitor in Sumo Logic. Check.png Check.png x-sized.png
Examples
Slack payload

{
     "attachments": [
         {
             "pretext": "Sumo Logic Alert for: *{{Name}}* by user USERNAME",
             "fields": [
                 {
                     "title": "Description",
                     "value": "{{Description}} {{TriggerTimeStart}}"
                 },
                 {
                     "title": "Query",
                     "value": "<{{QueryURL}}|{{Query}}>"
                 },
                 {
                     "title": "Time Range",
                     "value": "{{TriggerTimeRange}}"
                 }
             ],
             "mrkdwn_in": ["text", "pretext"],
             "color": "#29A1E6"
         }
     ]
 }

PagerDuty payload

{
    "service_key": "xxxxx",
    "event_type": "trigger",
    "description": "Monitor Alert on {{Name}}",
    "client": "Sumo Logic",
    "details": {
        "name": "{{Name}}",
        "query": "<{{QueryURL}} | {{Query}}>",
        "time": "{{TriggerTimeRange}} -- {{TriggerTime}} --"
    }
}

Email message

Monitor Alert: {{TriggerTimeRange}} on {{Name}}

Legacy Variables

This section provides the old variables available for alert notifications from Metrics Monitors and Scheduled Searches. The following table shows where the old variables are supported.

Variables Description  Metrics Monitors Scheduled Searches
 {{SearchName}} Description of the saved search or Monitor. In the delivered payload, this variable is replaced with the Name you assigned to the search or Monitor when you created it. Check.png Check.png
 {{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. Check.png Check.png
 {{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.
 
Check.png Check.png
 {{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. Check.png Check.png
 {{TimeRange}} The time range that triggered the alert. Check.png Check.png
 {{FireTime}} The start time of the log search or metric query that triggered the notification. Check.png Check.png
 {{AggregateResultsJson}} JSON object containing search aggregation results.

A maximum of 200 aggregate results can be sent via webhook.
x-sized.png Check.png

Not available with Email notifications
 {{RawResultsJson}} JSON object containing raw messages.

A maximum of 10 raw messages can be sent via webhook.
x-sized.png Check.png

Not available with Email notifications
 {{NumRawResults}} Number of results returned by the search. x-sized.png Check.png
 {{Results.fieldname}} The value returned from the search result for the specified field. For example, this payload specification:

{{Results.client_ip}} had {{Results.errors}} errors

Results in a subject line like this:

70.69.152.165 had 391 errors

A maximum of 200 aggregate results or 10 raw messages for this field can be sent via webhook.

A field name must match (case-insensitive) the field from your search and must be alphanumeric characters, underscores, and spaces. If you have a field name that has an unsupported character use the as operator to rename it.
x-sized.png Check.png

Email notifications only return the first result.
{{AlertThreshold}} The condition that triggered the alert (for example, above 90 at least once in the last 5 minutes) Check.png x-sized.png
{{AlertSource}} The metric and sourceHost that triggered the alert, including associated tags for that metric. Check.png x-sized.png
{{AlertSource.fieldname}} The value returned from the AlertSource object for the specified field name. Check.png x-sized.png
{{AlertID}} The ID of the triggered alert. Check.png x-sized.png
{{AlertStatus}} Current status of the time series that triggered (for example, Critical or Warning). Check.png x-sized.png
{{AlertCondition}} The condition that triggered the alert. x-sized.png x-sized.png

 

Example Authorization Header

Use HTTP Basic Authentication, this is a standard used across the world wide web, Sumo Logic doesn't require anything different or special. The username and password are concatenated, base64-encoded, and passed in the Authorization HTTP header. The Authorization field is constructed as follows:

  • Combine the username and password with a single colon.
  • Encode using the RFC2045-MIME variant of Base64. You can use any encoder, including the base64 search operator to do this.
  • 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 could be formed with a simple bash command 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": "{{Name}} ran over {{TimeRange}} at {{FireTime}}", 
    "results": "{{ResultsJson}}",
     "num": "{{NumQueryResults}}"
}

Hierarchical JSON

This example payload is hierarchical JSON. 

{ "event_type": "trigger",
    "description": "{{Description}}",
    "client": "Sumo Logic",
    "client_url": "{{SearchQueryUrl}}",
    "details": {
        "name: {{Name}}, time: {{TimeRange}}--{{FireTime}}, num: {{NumQueryResults}}, results: {{ResultsJson}}"
    }
}

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": "{{ResultsJson}}"
}

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.