Incident event REST API

You can use the Event API to report custom alert incident trigger events to New Relic. This event does not directly create an incident, but it does trigger the creation of the incident.

The API is an asynchronous endpoint. This means you can send a large volume of POSTS, reliably, with low-response latency.

Using the API: an overview

Here's the general process for sending custom incident events to New Relic via the incident event API:

Generate a for the account you want to report data to.
Before you get started creating custom attributes, review the Event API's limits and restricted characters.
Generate the JSON for your incident event that follows our JSON format guidelines.
Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using curl in a POST request.

Once you've started sending incident event data to New Relic, we recommend that you set up NRQL alert conditions to get notifications about parsing errors.

Example JSON

Your JSON payload may look something like this example.

[
  {
    "eventType": "NrAiIncidentExternal",
    "title": "Test",
    "description": "The latency is above threshold of 500000 MS",
    "state": "trigger",
    "source": "luna",
    "entityName": "testEntity",
    "entity.guid": "testEntity123",
    "aggregationTag.serviceId": 5,
    "aggregationTag.environment": "testing",
    "aggregationTag.errorId": 10543,
    "tag.stackTrace": "some stack trace...",
    "version": 1
  }
]

The eventType field must use NrAiIncidentExternal.

Send your incident event from the command line

Here's an example of how to use curl to send your JSON payload.

bash

$gzip -c example_incidents.json | curl --data-binary @-  \
>-X POST -H "Content-Type: application/json"  \
>-H "Api-Key: YOUR_LICENSE_KEY" -H "Content-Encoding: gzip" \
>https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT/events

Response
{"success":true, "uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}%

Once you've successfully sent your incident event data, you can see it in the alerts UI or by querying that data.

Incident event API specification

The incident event API uses the Event API's value types. For descriptions of these value types and guidelines on using them, see our event API JSON guidelines.

Advertencia

If you create two trigger events with the exact same aggregationTag, they will be aggregated to the same incident. Meaning, only one incident is created from multiple triggers.

Field	Description
`aggregationTag.` string, number, or timestamp*	REQUIRED Any attribute prefixed with `aggregationTag` will be used to aggregate trigger events together. In other words, two trigger events with the same aggregation tags are aggregated to the same incident. (Assuming none of the trigger events are resolve events). When resolving incidents, it's important that the resolve event include the same aggregation tags. Aggregations tags with reserved keywords are filtered out. For example, in a JSON payload with `aggregationTag.priority: 2` this key-value pair will be omitted in the incident event with these reserved keywords: `reserved_key: {"priority", "accountId", "originalAccountId", "policyId", "conditionId", "aggregationKey", "entityType", "entityName", "entityId", "violationUuid", "violationId", "nrIncidentId" }`
`state` enum: (`trigger`, `resolve`)	REQUIRED Whether the event should trigger a new incident or resolve an existing one. Updates to the incident can also be sent using trigger.
`priority` enum: (`low`, `medium`, `high`, `critical`)	The incident's priority. Default: `high`. Highest priority will be used when different priorities are sent.
`title` string	REQUIRED, when `state` is `trigger` The triggering event's title.
`source` string	REQUIRED, when `state` is `trigger` The origin of the incident, or the monitoring system that triggered it (not the entity that faulted).
`description` string	The triggering event's description.
`deepLinkUrl` string	A deep link to a page related to the incident.
`runbookUrl` string	A runbook URL.
`externalId` string	An external ID you can attach to the event. For example, it can be used to query for errors related to ingesting this event.
`entityName` string	The name of the entity that generated the incident.
`entity.guid` string	The ID of the entity that generated the incident.
`version` float	The current format's version.

Field

Description

aggregationTag.*

string, number, or timestamp

REQUIRED

Any attribute prefixed with aggregationTag will be used to aggregate trigger events together.

In other words, two trigger events with the same aggregation tags are aggregated to the same incident. (Assuming none of the trigger events are resolve events).

When resolving incidents, it's important that the resolve event include the same aggregation tags.

Aggregations tags with reserved keywords are filtered out. For example, in a JSON payload with aggregationTag.priority: 2 this key-value pair will be omitted in the incident event with these reserved keywords:

reserved_key: {"priority",  "accountId", "originalAccountId", "policyId", "conditionId", "aggregationKey", "entityType", "entityName", "entityId", "violationUuid", "violationId", "nrIncidentId" }

state

enum: (trigger, resolve)

REQUIRED

Whether the event should trigger a new incident or resolve an existing one. Updates to the incident can also be sent using trigger.

priority

enum: (low, medium, high, critical)

The incident's priority. Default: high.

Highest priority will be used when different priorities are sent.

title

string

REQUIRED, when state is trigger

The triggering event's title.

source

string

REQUIRED, when state is trigger

The origin of the incident, or the monitoring system that triggered it (not the entity that faulted).

description

string

The triggering event's description.

deepLinkUrl

string

A deep link to a page related to the incident.

runbookUrl

string

A runbook URL.

externalId

string

An external ID you can attach to the event.

For example, it can be used to query for errors related to ingesting this event.

entityName

string

The name of the entity that generated the incident.

entity.guid

string

The ID of the entity that generated the incident.

version

float

The current format's version.

Using the API: an overview .css-21sua1{background:none;border:none;width:0;padding:0;}

Example JSON

Send your incident event from the command line

Incident event API specification

Advertencia

Using the API: an overview