Generic REST API integration with Incident Response

Use generic integration when you do not find the required observability integration in our list of integrations. 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
    The Integrations landing page.
  3. 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.
  5. Click Generate Webhook.

    A webhook URL is generated.

    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 REST API.
  6. Click Save.
    The Parameters and the Sample payload tabs appear. In the Parameters tab you can map the appropriate alert fields to the fields from your payload. In the Sample payload tab, you can generate a sample alert based on the payload values provided in the parameter fields.
  7. Click the Parameters tab.
  8. Fill the details for the parameters, as required.
    Parameters in generic rest api integration.

    To add more parameters, click +Add parameters. With the details that you entered for each parameter, the sample payload is created.

    Table 1. Fields mapping
    Fields Description
    Parameters Represent the attributes of an alert. For example, the Description field is the short description of the alert.
    Mapping

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

    {
  "alert": {
  "state": "Open",
    "event": {
      "input": [
        {
          "type": "Subsystem - AX1",
          "name": "MDFADF1DF"
        }
      ],
      "datapoint": [
        { 
          "time": "1538639078000",
          "kind": "Disk usage",
          "name": [
            {
              "format": "healthy"
            },
            {
              "format": "unhealthy"
            }
          ]
        }
      ],
     "type": "Health Hazard"
    },
    "title": "90% of Disk is full",
    "priority": "Low"
  }
}

    All the values for the Mapping field must have JSON dot-walked values.

    In the sample JSON payload example, if you want the value of the alert state to be Open, then the Mapping field value should be alert.state. For source, if you want to assign Subsystem - AX1 which is in a JSON array, the value of the Mapping field must be mentioned as alert.event.input.[0].type.

    Note: Since input is an array and the value Subsystem - AX1 is in the 0th index of the array, you need to mention the index within square brackets like [0].

    Similarly, for metric_type, if you enter the mapping value as alert.event.datapoint.[0].name.[1].format, then the value that gets assigned is Unhealthy.
    Payload value Value is used while generating sample payload.
    If the value of the Mapping field is alert.state and the Payload value is Open, the sample payload that is generated is as follows:
    {"alert": {"state": "Open"}}
    Note: The first payload value is only for testing purpose and is not saved.
    First parameter value.
    +Add enumeration value

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

    Map the payload value with the alert state.
    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 values of an alert.
    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:
    Generic api event time.
    In the given example, the time when the event occurred is 2021-10-01 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 is assumed to be the Unix epoch time in milliseconds.
    • If an incorrect time format is given, the system time is considered.
    • If a correct time format is given but the value is incorrect, the system time is considered.
  9. Click Save.
    Note: Use the Sample payload tab to view the sample payload. The payload is to verify whether the integration is configured correctly in 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 check if any alert is created. The alert is generated from Incident Response and not from the monitoring tools.
    Sample payload created for REST API.