Enhance notifications using New Relic Connect

Limited
release

New Relic Connect enables you to customize New Relic webhooks to meet your team’s complex notification requirements. You can automatically send incident data to and from wherever you want, attaching relevant information. This way you no longer have to search for issues and can respond to incidents quickly. New Relic Connect enables you to:

  • Establish two-way integration with incident management tools.
  • Connect to additional notification platforms.
  • Customize webhook payloads with additional attributes.
  • Enrich webhooks with database information.

New Relic Connect can be used to build workflows that link your data from multiple tools and take intelligent actions. Currently supported destinations for New Relic Connect include a generic webhook, Amazon EventBridge, and Atlassian Jira.

Connect with:

Requirements for getting started with Connect

To get access to the limited release of this feature, contact your account representative or fill out this quick form.

Configure a New Relic Connect webhook

To configure a webhook using New Relic Connect, go to rpm.newrelic.com/apm > Alerts > Notification channels > New notification channel. See the webhooks information to learn more about these fields.

  1. For the Base Url, add https://connect.newrelic.com/YOUR_NEW_RELIC_ACCOUNT_ID
  2. In the Basic Auth area, set the username and password provided by your New Relic account representative. This is provided as an additional security measure and is required regardless of destination type.
  3. In the Custom Headers area, set the name to account_id and for Value, add your New Relic account ID.

Connect webhook payload parameters

In the Use Custom Payload area, you can add additional parameters to customize the webhook. Refer to the following table for a list of required and optional parameters to include for New Relic Connect incidents.

All of the default fields in the custom webhook payload are optional; if you leave the default fields, all of the information in those fields is included in the webhook. You can remove any fields you don't need.

Parameter Description
notification_channels

Required. This parameter replaces the functionality of the base URL originally specified in the webhook definition, and specifies the destinations for the enriched webhook. It has three fields: type, endpoint, and credentials.

You can specify an unlimited number of destinations for a given webhook.

{
"notification_channels": [
   {
   "type": "webhook",
   "endpoint": "https://webhook.address.com",
   "credentials": {
      "api_key": "1234",
      "api_key_header": "MyHeader",
      “api_key_header_prefix”: “Bearer”
      "username": "user",
      "password": "pass"
   }
},
notification_channels / type Required. Choose webhook or awseventbridge.
notification_channels / endpoint Required. The URL to send the event to.
notification_channels / credentials

Optional. Credentials are optional for webhooks; for Amazon EventBridge, this includes your aws_account_id and aws_region.

If the credentials field is not declared on a channel object, the webhook’s basic auth credentials (as defined in the customer setup section) are forwarded to the third-party channel.​

notification_channels / credentials / username Optional. Used for basic authentication. Required if password is specified.
notification_channels / credentials / password Optional. Used for basic authentication. Required if username is specified.
notification_channels / credentials / api_key Optional. A string token to pass in as an HTTP header. The default header is Authorization.
notification_channels / credentials / api_key_header Optional. Used to override which header sends the API key. Has no effect if the api_key field is not set.
notification_channels / credentials / api_key_header_prefix Optional. Add an optional prefix before the API key. A common requirement is to use the prefix Bearer for JWT authentication. Has no effect if the api_key field is not set.
email_status_report

Optional. Specify an email address that will receive an error report if the webhook fails.

“email_status_report”: “YOUR_EMAIL"

flatten_target

Optional. Add a new root-level field to the webhook payload for each New Relic Alerts target that is associated with the incident. This can be helpful for parsing the payload in incident management tools with a rigid structure or predefined fields.

“flatten_target”: “true”

nrql_execution

Optional. Include an NRQL query that runs when a new incident is triggered; the query results are attached to the webhook payload. For guidance on writing NRQL queries for this field, see the New Relic Query Language documentation. Review the query results in the events array field of the final webhook payload.

"nrql_execution”: “SELECT * FROM Transaction where appName={{incident_id}} SINCE 1 hour ago”

nrql_credentials

Required if using nrql_execution. Insights API key from New Relic.

“nrql_credentials”: “YOUR_NEW_RELIC_INSIGHTS_API_KEY”

account_id

Required if using nrql_execution. Your New Relic account ID.

“account_id”: “YOUR_NEW_RELIC_ACCOUNT_ID”

map_attributes

Optional. An object containing instructions for creating new fields required for the downstream notification channel. Use this field to populate webhook payload fields into new string fields. Each key in the map_attributes object specifies a new required field in the final payload, while each value contains a string template describing what original payload values to use while constructing the result.

The map_attributes projection occurs after the NRQL query, and can then use NRQL results in the construction of new fields. In the example below, two new fields are defined to be added to the final webhook payload. short_descriptionis copied from an existing field in the default webhook payload called condition_name. The second field, description, is combined from the static string First event and a dynamic value obtained from the first NRQL event. This is appended using the nrql_execution feature. To learn about the specific variable, make sure to run your NRQL query using the REST API and inspect the return answer to map all the available fields correctly.

"map_attributes": { "short_description": "{{condition_name}}", "description":"First event: {{events[0].id}}", }

Use New Relic Connect with Amazon EventBridge

New Relic Connect makes it easy to hook New Relic events into AWS services with EventBridge, Amazon's serverless event bus.

  1. Follow the steps to create a New Relic webhook with a custom payload configured for New Relic Connect. Under notification_channels in the custom payload:
    • Set the type to awseventbridge.
    • Set the endpoint to the name of the new event bus you want to create in EventBridge.
    • Set the credentials to your aws_account_id and aws_region.

    Example

    "notification_channels": [
       {
          "type": "awseventbridge",
          "endpoint": ""
          "credentials": {
             "aws_account_id": ""
             "aws_region": ""
          }
       }
    ]
  2. Save and send a test event. This first event creates a new partner event source in EventBridge automatically.
  3. In the Amazon EventBridge UI, click on the new Partner Event Source that was created by your test event, and follow the process to associate it with an event bus.
  4. Forward the EventBridge event to whatever AWS service you want. After EventBridge rules are configured, future events triggered by your New Relic webhook are pushed to those services automatically.

    To create more complex event filters, add a resources webhook field in the New Relic custom payload. EventBridge automatically gives you the option to use this field’s contents as filters in new rules. For more information about configuring EventBridge rules, see the EventBridge Documentation.

Use New Relic Connect with Atlassian Jira

Jira is a popular issue and project tracking software that many site reliability engineering (SRE) and DevOps teams use in their incident management and response cycles. New Relic Connect makes it easy to set up a two-way integration with Jira and enhance existing incidents with additional information from other services.

  1. Follow the steps to create a New Relic webhook with a custom payload configured for New Relic Connect. Under notification_channels in the custom payload:
    • Set the type to Jira.
    • Set the endpoint to your Jira instance URL.
    • Set the credentials using the email address for your Jira account as your username and a generic Jira token for your password.

    Example:

    "notification_channels": [
       {
          "type": "jira",
          "endpoint": """
          "credentials": {
             "username": ""
             "password": """
          }
       }
    ]
  2. Set additional parameters in the webhook payload:
    • incident_id: (required) New Relic incident ID
    • project: (required) the Jira project ID for new tickets to be created in
    • assignee: (optional) the Jira username to assign new tickets to by default
    • watchers: (optional) array of Jira user names to be assigned as watchers for new incidents
  3. (Optional) Follow the above instructions to map attributes from the New Relic alert to Jira fields. All single-line text fields (default and custom) are supported; only default (not custom) multi-line text fields are supported.
  4. In the Jira UI, create a new field called new relic incident id for the New Relic incident ID to map to (required) and add it to the screen for the project you chose in step 2.
  5. To enable two-way integration between Jira and New Relic, in the Jira UI, under Settings > System > Webhooks (under “Advanced”) > Create New, turn on “updated” for the issue.
  6. In the URL field, enter http://connect.newrelic.com/jiraStatusChange and append the following parameters:
    • nrApiKey=”<REST API key for New Relic>"
    • jiraApiKey=”<generic Jira token>"
    • username=”<your New Relic username>"
  7. Once this is configured, if the status of the Jira ticket changes to anything other than “Done,” the New Relic Alert status updates to “Acknowledged.” Once the Jira ticket is moved to “Done,” it is marked as “Closed” in the New Relic UI.

    Full payload example

    {
      "incident_id": "$INCIDENT_ID",
      "condition_name": "$CONDITION_NAME",
      "short_description": "Example description",
      "email_status_report": "noreplay@connect.newrelic.com",
      "notification_channels": [
        {
          "type": "jira",
          "endpoint": "https://example-instance.atlassian.net/",
          "credentials": {
            "username": "example@youremail.com",
            "password": "examplepassword"
          },
          "project": "EXAMPLE",
          "assignee": "admin",
          "watchers": []
        }
      ],
      "i_will_be_used_in_query": "search",
      "flatten_target": true,
      "nrql_credentials": "",
      "nrql_execution": "SELECT * FROM Transaction where appName={{i_will_be_used_in_query}}",
      "map_attributes": {
        "short_description": "Example description here",
        "summary": "Example summary here",
        "description": "Last transaction: {{events[0].name}}"
      }
    }
    

For more help

Recommendations for learning more: