Skip to main content
Version: 0.4 · current

Connect New Relic

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Connect a New Relic account to bring its infrastructure hosts, APM services and synthetic monitors into Excubius, with their golden metrics and their open issues. This guide shows the least-privilege setup on the New Relic side, how to add the source and how to send issues by webhook.

Before you begin​

  • You need the Entity admin role on the entity the account belongs to, for example Ciguapa Inc..
  • In New Relic, you can create a user or a service user, an API key and a workflow on the account.
  • The feature sources.newrelic is on. See Sources.

What Excubius reads​

New Relic is read through NerdGraph with GraphQL queries only, never mutations.

PhaseWhatDefault interval
InventoryEntity search in the account: infrastructure hosts (Windows, Linux or macOS by their operating system tag), APM applications and synthetic monitors, optionally narrowed by an entity search condition15 minutes
MetricsThe summaries the same search returns, without NRQL, so they cost little quota. Host CPU, memory and disk feed the Windows and Linux host checks; APM and synthetics feed the New Relic checks5 minutes
AlertsAI issues in the states CREATED and ACTIVATED of the last 30 days, one alert per issue and entity5 minutes in Polling; reconciliation every 15 minutes in Hybrid

Prepare New Relic​

  1. Create a user, or use a service user, whose role is read only on the account, for example the built-in All product read only role.
  2. Signed in as that user, open API keys and create a key of type User. Copy the key; it starts with NRAK-. License, browser and ingest keys do not work.
  3. Note the account ID and the data centre, US or EU.

This user key is all Excubius needs to poll. A source in Webhook only mode needs neither the key nor the account ID.

Add the source​

  1. Open Settings › Sources, select Add a source and choose New Relic.
  2. Under General, enter a Name, such as New Relic Ciguapa, and choose the Entity.
  3. Under Connection, enter the Account ID, the Region and the User API key.
  4. Under What to read, keep Hosts, APM services, Synthetic monitors and Golden metrics, or clear what you do not want. Without Golden metrics, the entities come in without their metrics.
  5. Optionally, enter an Entity filter, a New Relic entity search condition such as tags.environment = 'production'. Use it when one account covers several clients.
  6. Under Ingest mode, keep Hybrid (recommended).
  7. Optionally, under Webhook, enter a Webhook secret that New Relic will send with every webhook.
  8. Select Create source and copy the webhook URL. It is shown only once.

Send issues by webhook​

In Hybrid or Webhook only mode, set up New Relic to push its issues:

  1. In New Relic, open Alerts › Destinations and add a Webhook destination with the URL Excubius showed. If you set a webhook secret, add the header Authorization: Bearer <secret>, or X-Webhook-Secret: <secret>.

  2. Create a workflow that filters the issues you want in Excubius and notifies that destination with this payload template:

    {
    "issueId": {{ json issueId }},
    "state": {{ json state }},
    "priority": {{ json priority }},
    "title": {{ json annotations.title.[0] }},
    "issuePageUrl": {{ json issuePageUrl }},
    "triggerEvent": {{ json triggerEvent }},
    "createdAt": {{ createdAt }},
    "updatedAt": {{ updatedAt }},
    "conditionNames": {{ json accumulations.conditionName }},
    "policyNames": {{ json accumulations.policyName }},
    "entityGuids": {{ json entitiesData.ids }},
    "entityNames": {{ json entitiesData.names }}
    }

    New Relic's default template works too.

  3. Notify on activated and closed, so alerts close in Excubius as well.

Test and sync​

  1. On the source page, select Test. Each read is listed with its result: credentials, account, inventory and alerts.
  2. Select Sync now to bring the inventory, metrics and alerts in without waiting.

Hosts appear as resources, matched with the same servers from other sources. APM services appear as Application (APM) resources and monitors as Synthetic monitor resources, with their checks. Open issues appear in the Alert inbox, with a link to New Relic.

Choose the mode​

ModeYou get
HybridIssues at once by webhook; inventory and metrics by polling; a reconciliation that closes what was closed in New Relic while a webhook was lost
PollingEverything by polling. Issues appear within the alert interval, 5 minutes by default
Webhook onlyIssues only, with no inventory or metrics, and no key stored