Let your customers receive alerts in their own on-call tools

Key takeaways

One customer may want theirs sent via PagerDuty. Another Grafana, Opsgenie or an internal HTTP endpoint as the case may be.

If you implement that requirement provider by provider, each integration will need credential handling, payload mapping, retries, and delivery logs. It may even require you to create workflows for each customer which adds more duplication.

Novu’s Tool channel gives you a different model. You define the event once, add one Tool step to the workflow, and activate the Tool integrations you support. Each customer’s destination is stored as subscriber configuration. Your application can then trigger the same workflow without branching on the provider.

How one workflow supports different customer destinations

The Tool channel can have several active integrations just like any other channel in Novu. When its workflow step runs, Novu delivers the authored content through active integrations with destinations configured for the subscriber.

When you connect a tool in the Integration Store, Novu gives you an integrationIdentifier. That integration holds no credential of its own, it’s just the anchor. Each customer’s actual destination lives in a channel endpoint: their routing key, their API key, their webhook URL, encrypted at rest and tied to a subscriber, which here just stands in for one customer’s on-call destination.

The alert goes to the subscriber’s own on-call destination, and every workflow triggered for a tool step shows up in the Activity feed.

Also, just like other channels, you can have several Tool integrations active at once, and a single Tool step delivers through all of the active ones in parallel.

What stops every customer from being paged on all four tools is the endpoint. A subscriber only has channel endpoints for the tools they actually connected, and an endpoint’s type is what ties them to a provider. In code that’s literally a field:

type: "pagerduty_service"   // this endpoint routes to PagerDuty

When the Tool step runs for a subscriber, it delivers on the providers that subscriber has an endpoint for and skips the ones they don’t. So a customer who connected only Opsgenie gets the Opsgenie page and nothing else, with no if statements in your workflow.

When a customer brings something with no native provider

Sooner or later a customer runs an internal incident service, a queue, or a tool they built themselves. That’s what Tool Webhook is for, and it’s just another tool you enable in the Integration Store.

It has two modes:

• Static uses one URL on the integration for everyone, which is handy when the endpoint is yours.
• Dynamic is the multi-tenant one: per-subscriber endpoints, the same registration pattern as the others, except a subscriber can register more than one and Novu delivers to each of them.

It won’t fall back to the static URL, so a subscriber with no dynamic endpoints just gets skipped, same as the native providers.

Each endpoint carries its own URL, headers, and method. If you set a signing secret on the integration, Novu adds an HMAC-SHA256 signature in an X-Novu-Signature header, which the receiver verifies against the raw request body before parsing anything.

The full signing and body-merge details are in the Tool Webhook docs.

Here’s how the four providers line up:

Build the customer alert workflow

Create the active integrations and shared workflow first. Register customer credentials afterward.

Prerequisites

You need:

• A Novu account and secret key
• Access to the Novu dashboard
• A server-side TypeScript application with @novu/api installed or any SDK we support. You can use a plain API request, if we don't support the language you use.
• Test credentials or webhook details for the destinations you plan to connect

1. 1

   Add the Tool providers

   In the Novu dashboard:

   1. Open Integrations Store.
   2. Select Connect Provider.
   3. Open the Tool tab.
   4. Add each tool you want to support: PagerDuty, Opsgenie, Grafana, and Tool Webhook.

   

   All four can be active together, because they do not need any shared environment credentials. Each integration anchors subscriber-specific endpoints, so give it a clear identifier for endpoint registration.

2. 2

   Create one workflow for the event

   Create a workflow with the identifier customer-sync-failed. Add one Tool step and use this message:

   Data sync {{payload.syncId}} failed for {{payload.customerName}}

   Each active integration maps the same content to its provider payload:

   • PagerDuty uses it as the incident summary.
   • Opsgenie uses it as the alert message and truncates content longer than 130 characters.
   • Grafana uses it as the alert group title.
   • Tool Webhook sends it in the content property of the JSON body.

   Use provider content overrides when a destination needs additional fields or different formatting.

   Tool participates in workflow and subscriber channel preferences. You can also configure skip on failure so later workflow steps continue after a Tool delivery fails.

Register the destination each customer chooses

Registering a channel endpoint connects a customer’s choice to the workflow. Use an authenticated settings flow where the customer selects a provider and supplies the required key or URL.

The backend should verify that the signed-in user can manage the customer account before sending those details to Novu. The following TypeScript example handles all four endpoint types with one function:

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY!,
});

type EndpointConfig =
  | {
      type: 'pagerduty_service';
      integrationIdentifier: string;
      endpoint: {
        routingKey: string;
        region: 'us' | 'eu';
      };
    }
  | {
      type: 'opsgenie_integration';
      integrationIdentifier: string;
      endpoint: {
        apiKey: string;
        region: 'us' | 'eu';
      };
    }
  | {
      type: 'grafana_oncall_integration';
      integrationIdentifier: string;
      endpoint: {
        url: string;
        authToken?: string;
      };
    }
  | {
      type: 'tool_webhook';
      integrationIdentifier: string;
      endpoint: {
        url: string;
        headers?: Record<string, string>;
        method?: 'POST' | 'PUT' | 'PATCH';
      };
    };

export async function registerAlertDestination(
  subscriberId: string,
  config: EndpointConfig
) {
  return novu.channelEndpoints.create({
    ...config,
    subscriberId,
    createSubscriberIfMissing: true,
  });
}

For PagerDuty, Opsgenie, and Grafana, a subscriber can have one endpoint per integration. A duplicate create request returns 409 Conflict. Store the endpoint identifier so your backend can update or delete it later.

Dynamic Tool Webhook allows multiple endpoints per subscriber on the same integration. Novu sends one request to each endpoint.

Trigger the same workflow for every customer

The trigger path should describe the event and identify its recipient. It does not need to know which provider the customer selected.

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY!,
});

type SyncFailure = {
  syncId: string;
  customerName: string;
  sourceSystem: string;
  failureReason: string;
  dashboardUrl: string;
};

async function sendSyncFailure(
  subscriberId: string,
  payload: SyncFailure
) {
  return novu.trigger({
    workflowId: 'customer-sync-failed',
    to: { subscriberId },
    payload,
  });
}

const failure: SyncFailure = {
  syncId: 'sync_01K4M6W9P2',
  customerName: 'Customer A',
  sourceSystem: 'warehouse',
  failureReason: 'Connection timed out after 30 seconds',
  dashboardUrl: 'https://app.example.com/syncs/sync_01K4M6W9P2',
};

await sendSyncFailure('customer-a-oncall', failure);
await sendSyncFailure('customer-c-oncall', {
  ...failure,
  customerName: 'Customer C',
});

Both calls use the same workflow and payload structure. At delivery time, the single Tool step runs against the active Tool integrations and resolves the endpoints associated with each subscriber:

• customer-a-oncall receives a PagerDuty delivery.
• customer-c-oncall receives a Grafana delivery.
• A provider delivery without a matching subscriber endpoint is skipped without creating an alert or raising an error.
• A subscriber with PagerDuty and Tool Webhook endpoints receives the Tool step through both integrations.
• A subscriber with several dynamic webhook endpoints receives one request per endpoint.

PagerDuty, Opsgenie, and Grafana use deterministic identifiers to prevent retries from creating duplicate alerts. Activity shows the provider, status, and attempts.

For Tool Webhook, Novu merges the integration body, rendered step content, and overrides. Rendered content is sent as content and takes precedence over the same integration-level key.

With a signing secret, Novu sends an HMAC-SHA256 digest in X-Novu-Signature. Verify it against the raw request body before parsing the JSON.

What changes when you add another destination

An existing provider

If a new customer uses a provider already represented in the workflow, register the corresponding channel endpoint for that subscriber. The trigger code remains unchanged.

A custom HTTP destination

If a destination accepts HTTP requests but has no native Tool provider, use dynamic Tool Webhook. This general delivery path does not reproduce provider-specific features such as PagerDuty incident actions.

A new native provider

A new native provider still requires provider support and an active integration, but the existing Tool step can remain unchanged.

Use these guides for provider-specific setup:

PagerDuty Tool integration

Opsgenie Tool integration

Grafana Tool integration

Tool Webhook integration

Create a channel endpoint

Your alerts. Your customers’ on-call tools.

Use one Novu workflow to deliver alerts to the tools each customer connects.

Set up tool integrations

Frequently asked questions