Tool

The Tool channel delivers a payload from a workflow to an operational system. Use it to page on-call, open an incident, or POST JSON to an endpoint you control. It is a channel step, like email or SMS. Novu sends through a Tool integration in the Integration Store. It is not a replacement for step.custom, which runs arbitrary code in your bridge and returns structured results to later steps.

Connect a Tool provider before triggering. PagerDuty, Opsgenie, and Grafana route per subscriber via channel endpoints. Tool webhook can use a shared URL (static) or per-subscriber URLs (dynamic).

When to use `step.tool`

Use `step.tool` when	Use `step.custom` when
You want Novu to deliver to PagerDuty, Opsgenie, Grafana, or a webhook	You need to fetch or transform data in your bridge
Delivery should use a configured integration and Activity feed	The result must be reused in later steps
You need provider-specific fields (severity, tags, extra JSON keys)	You are calling an API that has no Tool provider

A common pattern is to fetch in step.custom, then page with step.tool using that result.

Providers

Provider	What `body` becomes	Setup
PagerDuty	Incident `payload.summary`	Per-subscriber Events API v2 routing key
Opsgenie	Alert `message` (truncated at 130 characters)	Per-subscriber API key
Grafana	Alert group `title` (truncated at 1024 characters)	Per-subscriber webhook URL
Tool webhook	Request JSON `content`	Static URL on the integration, or dynamic subscriber endpoints

If a subscriber has no channel endpoint for an endpoint-routed provider (or no dynamic webhook URLs), Novu marks the Tool step skipped for that subscriber. Other subscribers on the same trigger are unaffected.

Define a tool step

The resolver must return a body string. That string is the default content sent to the provider.

await step.tool('page-oncall', async () => {
  return {
    body: 'Payment failed for order ORD-12345',
  };
});

Workflow with payload

import { workflow } from '@novu/framework';
import { z } from 'zod';

export const orderFailed = workflow(
  'order-failed',
  async ({ step, payload, subscriber }) => {
    await step.tool('page-oncall', async () => ({
      body: `Payment failed for order ${payload.orderNumber} (${subscriber.subscriberId}): ${payload.reason}`,
    }));
  },
  {
    payloadSchema: z.object({
      orderNumber: z.string(),
      reason: z.string(),
    }),
  }
);

Trigger the workflow as usual. Delivery uses the subscriber’s Tool endpoints for that environment.

await orderFailed.trigger({
  to: 'user-123',
  payload: {
    orderNumber: 'ORD-12345',
    reason: 'payment_declined',
  },
});

Provider overrides

Use the providers option to pass fields the shared body schema does not cover. Keys are Tool provider IDs: pagerduty, opsgenie, grafana, and tool-webhook. Only the override for the integration that actually sends is applied. You can define several; unused ones are ignored.

PagerDuty
Opsgenie
Grafana
Tool webhook

await step.tool(
  'page-oncall',
  async () => ({
    body: 'Payment failed for order ORD-12345',
  }),
  {
    providers: {
      pagerduty: async ({ outputs }) => ({
        severity: 'error',
        source: 'checkout',
        summary: outputs.body,
        custom_details: {
          runbook: 'https://runbooks.example.com/payments',
        },
      }),
    },
  }
);

PagerDuty defaults severity to critical and source to novu when you omit those fields. See incident payload defaults.

await step.tool(
  'page-oncall',
  async () => ({
    body: 'Payment failed for order ORD-12345',
  }),
  {
    providers: {
      opsgenie: async ({ outputs }) => ({
        message: outputs.body,
        description: 'Card declined after 3 retries. Customer is blocked at checkout.',
        priority: 'P1',
        tags: ['payments', 'checkout'],
        source: 'novu',
      }),
    },
  }
);

Opsgenie truncates message at 130 characters. Put detail in description (up to 15,000 characters). See alert payload defaults.

await step.tool(
  'page-oncall',
  async () => ({
    body: 'Payment failed for order ORD-12345',
  }),
  {
    providers: {
      grafana: async ({ outputs }) => ({
        title: outputs.body,
        message: 'Card declined after 3 retries.',
        state: 'alerting',
        link_to_upstream_details: 'https://app.example.com/orders/ORD-12345',
      }),
    },
  }
);

Send state: 'ok' with the same alert_uid to auto-resolve. See alert payload defaults.

await step.tool(
  'notify-ops',
  async () => ({
    body: 'Payment failed for order ORD-12345',
  }),
  {
    providers: {
      'tool-webhook': async ({ outputs }) => ({
        alert_type: 'incident',
        title: outputs.body,
      }),
    },
  }
);

The rendered body is always sent as content on the JSON request. Extra keys from the override merge into that object. See request shape.

You can also use _passthrough to merge extra body, headers, or query into the underlying provider request. See provider overrides.

Step controls

Expose copy that non-developers can edit in the dashboard without changing code.

import { z } from 'zod';

await step.tool(
  'page-oncall',
  async (controls) => ({
    body: controls.body,
  }),
  {
    controlSchema: z.object({
      body: z.string().default('An incident requires attention.'),
    }),
    providers: {
      pagerduty: async ({ controls, outputs }) => ({
        summary: outputs.body,
        severity: 'error',
        source: 'checkout',
      }),
    },
  }
);

After you sync the workflow, the dashboard renders a body field for this step. Payload data still comes from novu.trigger. Learn more about controls.

Skip the step

Skip delivery from previous-step results, payload flags, or subscriber data.

workflow('order-failed', async ({ step, payload }) => {
  const order = await step.custom(
    'load-order',
    async () => {
      const record = await db.orders.find(payload.orderNumber);

      return {
        orderNumber: record.id,
        alreadyPaged: record.pagerDutyIncidentId != null,
      };
    },
    {
      outputSchema: {
        type: 'object',
        properties: {
          orderNumber: { type: 'string' },
          alreadyPaged: { type: 'boolean' },
        },
        required: ['orderNumber', 'alreadyPaged'],
      },
    }
  );

  await step.tool(
    'page-oncall',
    async () => ({
      body: `Payment failed for order ${order.orderNumber}`,
    }),
    {
      skip: () => order.alreadyPaged || payload.severity === 'low',
    }
  );
});

skip runs at send time, not during dashboard preview. See skip.

Channel preferences

Disable Tool for a workflow (or leave it subscriber-controlled) with preferences.channels.tool:

workflow(
  'order-failed',
  async ({ step, payload }) => {
    await step.tool('page-oncall', async () => ({
      body: `Payment failed for order ${payload.orderNumber}`,
    }));
  },
  {
    preferences: {
      channels: {
        tool: { enabled: true },
      },
    },
  }
);

Output

The resolver returns { body: string }. The step does not return a result, so you cannot branch later steps on whether the provider accepted the request. See the Tool step reference.

Tool step reference

Output schema and SDK types.

Tool webhook

Static vs dynamic routing, request body merge, and HMAC signatures.

PagerDuty

Per-subscriber routing keys and Events API v2 incident fields.

Custom step

Fetch data in your bridge, then pass it into step.tool.

Getting Started

Core Concepts

Channels

Content

Advanced Features

API Reference

Deployment

When to use `step.tool`

Providers

Define a tool step

Workflow with payload

Provider overrides

Step controls

Skip the step

Channel preferences

Output

Tool step reference

Tool webhook

PagerDuty

Custom step

​When to use step.tool

​Providers

​Define a tool step

​Workflow with payload

​Provider overrides

​Step controls

​Skip the step

​Channel preferences

​Output

​Related

Tool step reference

Tool webhook

PagerDuty

Custom step

When to use `step.tool`

Providers

Define a tool step

Workflow with payload

Provider overrides

Step controls

Skip the step

Channel preferences

Output

Related