Generic webhook integration with Incident Response

Use the generic integration when you do not find the required observability integration in our list of integrations. The generic integration is an alternate approach that helps you customize and send an alert to Incident Response.

Before you begin

Role required: Responder, Manager, or Administrator

Procedure

  1. Log in to Incident Response.
  2. On the navigation pane, click Integrations.
    Figure 1. Integrations landing page
    Integrations landing page.
  3. Under Available integrations, click the Generic REST API integration card.
  4. On the form, fill the fields.
    Field Description
    Name Name of the integration.
    Status Status of the integration such as enabled or disabled.
    Note: You can modify this field only after the webhook is generated.
    Description Brief summary about the services of the integration.
    Integration URL The URL of the home page of the monitoring tool that sends alerts.
    Tags Tags that can help users search for the integration.
    Service Name of the service that you want to associate with the integration.

    A service represents a functional outcome like networking, payments, or HR services, that is owned by one team. You might need multiple tool integrations to monitor each technical service and receive events from those tools.
  5. Click Generate Webhook.

    A webhook URL is generated. A set of instructions on how to configure generic webhook to send alerts to Lightstep Incident Response is mentioned at the end of the page. For more information on the integration, click the documentation link mentioned below the name of the integration.

    A webhook URL is generated.
    Copy the webhook by clicking the copy icon (Copy the webhook URL.) and paste it in a safe place because you will need it when configuring the webhook in your monitoring tool.
  6. Click Save.
  7. Click the Field mapping tab.
    The Field mapping section lets you map the alert fields from your monitoring tool to the alert fields of Lightstep Incident Response so that your alert can be processed correctly.
  8. Fill the alert mapping details to map your alert to a Lightstep Incident Response alert.
    Note: Field mapping includes two enumerations (state and severity) and several individual fields. To add more alert fields, click +Add parameters that appears at the end of the page.
    Parameters in the generic webhook integration.

    With the details that you entered for each alert field, the sample alert is created.

    Table 1. Fields mapping
    Fields Description
    Field name Represent the attributes of a Lightstep Incident Response alert. For example, the corresponding attribute of the description field is the short description of the alert.
    Mapping

    Enter the JSON path to the appropriate mapping field in the incoming alert payload. The path is the dot-walked representation of a specific JSON payload field. For example, the mapping field alert.state represents the value Open in the following sample JSON format.

    Here is a new JSON with sample mapping and values which are represented in the sample alert panel:
    {
    "alert": {
        "state": "Open",
        "severity": "Very high",
        "time": "2021-10-28 12:40:00",
        "title": "90% of disk is full",
        "source": "MyMonitoringTool",
        "original": {
            "node": "Server1",
            "subsystem": "Disk",
            "kpi": "Free Capacity",
            "kpi_unit": "GB"
        }
    },
    "version": "1.0"
}
    Alert value Value is used while generating sample alert.
    If the value of the Mapping field is alert.state and the Alert value is Open, the sample alert would contain the following:
    "alert": {"state": "Open"}
    Note: The alert value column is used only to generate sample alert.
    Alert value.
    +Add enumeration value

    Map the alert value with the alert state or severity by clicking +Add enumeration value and select the appropriate value from the list.

    Map the alert value with the alert state.
    Note: In the example above, it is explicitly stated that a blank severity value is interpreted as a Warning severity. If a blank value is not specified, it will be implicitly interpreted as a Warning severity. Similarly, if a blank state value is not specified, it will be implicitly interpreted as New.

    For state and severity, the messages Alert states and Alert severities indicate the number of values you have mapped out of all available alert values for a Lightstep Incident Response alert. It is acceptable to only configure a subset of them. For example, you could configure all 3 alert severity values from your monitoring tool to map to 3 alert severities in Lightstep Incident Response. Alternatively, you could have 7 alert severity values from your monitoring tool to map to the only 6 alert severities in Lightstep Incident Response.
    Fields used to create an alert key.
    Note: The five fields, source, node, resource_name, metric_name, and metric_type are used together to create an alert key. If that alert key does not yet exist in Lightstep Incident Response, a new alert is created. If the incoming alert contains an alert key which corresponds to another alert in Lightstep Incident Response, that new alert is used to update the existing alert and notes are added in the Alert timeline in the alert Details view.
    The state of an alert can be one of the following:
    State Description
    New The alert is unacknowledged and requires user action.
    Closing The alert is closed and no further user action is required.
    The severity of an alert can be one of the following:
    Severity Description
    Critical Immediate action is required. The resource is either not functional or critical problems are imminent.
    Major Major functionality is severely impaired or performance has degraded.
    Minor Partial, non-critical loss of functionality or performance degradation occurred.
    Warning Attention is required, even though the resource is still functional.
    OK An alert is created. The resource is still functional.
    Clear No action is required. An alert is not created from this event. Existing alerts are closed.
    The event_time is the time when the event occurred. The format of the incoming event time in the payload must be mentioned in the Format field as follows:
    The generic api event time.
    In the given example, the time when the event occurred is 2021-10-28 12:40:00 and the corresponding format is YYYY-MM-dd hh:mm:ss. The format string consists of the following abbreviations:
    Field Form
    Year YYYY
    Month MM
    Day of month dd
    Hour (12-hour time) hh
    Hour (24-hour time) HH
    Minute mm
    Second ss
    Note:
    • If the time format is not mentioned, the incoming time format is assumed to be the Unix epoch time in milliseconds.
    • If an incorrect time format is given, the time when the alert is received by Lightstep Incident Response is considered.
    • If a correct time format is given but the value is incorrect, the time when the alert is received by Lightstep Incident Response is considered.
  9. Click Save.
    Note: You must click Save after completing the field mappings and before clicking Send sample alert.

    Use the Sample alert section to view the generated sample alert. The sample alert is to verify whether the integration is configured correctly in Lightstep Incident Response. To test whether an alert is getting generated, click Send sample alert and from the navigation pane on your instance, click Alerts to view the sample alert you created. The alert is generated from Incident Response and not from the monitoring tool.