Trigger event

Trigger event is the main (and only) way to send notifications to subscribers. The trigger identifier is used to match the particular workflow associated with it. Maximum number of recipients can be 100. Additional information can be passed according the body interface below. To prevent duplicate triggers, you can optionally pass a transactionId in the request body. If the same transactionId is used again, the trigger will be ignored. The retention period depends on your billing tier.

POST /v1/events/trigger

TypeScript

TypeScript

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

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.trigger({
    workflowId: "workflow_identifier",
    payload: {
      "comment_id": "string",
      "post": {
        "text": "string",
      },
    },
    overrides: {},
    to: "SUBSCRIBER_ID",
    actor: "<value>",
    context: {
      "key": "org-acme",
    },
  });

  console.log(result);
}

run();

201

{
  "acknowledged": true,
  "error": [
    "<string>"
  ],
  "transactionId": "<string>",
  "activityFeedLink": "<string>",
  "jobData": {}
}

Authorizations

Authorization · string · header · required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

idempotency-key · string

A header for idempotency purposes

Body

application/json

name · string · required

The trigger identifier of the workflow you wish to send. This identifier can be found on the workflow page.

Example:

"workflow_identifier"

to · Option 1 · object · object · string[] Option 2 · string Option 3 · object Option 4 · object · required

The recipients list of people who will receive the notification. Maximum number of recipients can be 100.

Show child attributes

payload · object

The payload object is used to pass additional custom information that could be used to render the workflow, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.

Example:

{
  "comment_id": "string",
  "post": { "text": "string" }
}

overrides · object

This could be used to override provider specific configurations

Show child attributes

transactionId · string

A unique identifier for deduplication. If the same transactionId is sent again, the trigger is ignored. Useful to prevent duplicate notifications. The retention period depends on your billing tier.

actor · string object

It is used to display the Avatar of the provided actor's subscriber id or actor object.

If a new actor object is provided, we will create a new subscriber in our system

tenant · string object

It is used to specify a tenant context during trigger event. Existing tenants will be updated with the provided details.

context · object

Show child attributes

Response

201

application/json

Created

acknowledged · boolean · required

Indicates whether the trigger was acknowledged or not

status · enum<string> · required

Status of the trigger

Available options: error, trigger_not_active, no_workflow_active_steps_defined, no_workflow_steps_defined, processed, no_tenant_found, invalid_recipients

error · string[]

In case of an error, this field will contain the error message(s)

transactionId · string

The returned transaction ID of the trigger

activityFeedLink · string

Link to the activity feed for this trigger event

jobData · object