Events

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

Request body

namestring required

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

payloadobject

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.

bridgeUrlstring

Optional Bridge Endpoint URL used to route this trigger to a specific Bridge application. Useful during local development when multiple engineers share an organization: set this to your personal tunnel URL from npx novu@latest dev (for example via NOVU_BRIDGE_URL) so app-fired triggers hit your machine instead of the environment's synced Bridge URL. Must be a publicly reachable https URL — private or localhost addresses are rejected.

agentIdstring nullable

Override the workflow-assigned agent for this trigger using the public agent identifier. Omit to use the workflow default; pass null to disable agent routing for this execution.

transactionIdstring

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.

contextobject

Example request

{
  "name": "workflow_identifier",
  "payload": {
    "comment_id": "string",
    "post": {
      "text": "string"
    }
  },
  "bridgeUrl": "https://your-tunnel.novu.co/api/novu",
  "overrides": {
    "steps": {
      "email-step": {
        "providers": {
          "sendgrid": {
            "templateId": "1234567890"
          }
        },
        "layoutId": "step-specific-layout"
      }
    },
    "channels": {
      "email": {
        "layoutId": "promotional-layout-2024"
      }
    },
    "providers": {
      "sendgrid": {
        "templateId": "1234567890"
      }
    }
  },
  "agentId": "support-agent",
  "to": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "avatar": "https://example.com/avatar.jpg",
      "locale": "en-US",
      "timezone": "America/New_York"
    }
  ],
  "actor": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "avatar": "https://example.com/avatar.jpg",
    "locale": "en-US",
    "timezone": "America/New_York"
  }
}

Response

Created

acknowledgedboolean required

Indicates whether the trigger was acknowledged or not

Status of the trigger

errorstring[]

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

transactionIdstring

The returned transaction ID of the trigger

activityFeedLinkstring

Link to the activity feed for this trigger event

jobDataobject

Changes

Changed in 5 of the 13 revisions of this API.620

Aug 30, 20268bc1670bbd1333See the full diff
- ▲
  removed the enum value novu-agent-chat of the request property ///////
  request-property-enum-value-removed
- ▲
  removed the enum value novu-agent-chat of the request property ///////
  request-property-enum-value-removed
- ▲
  removed the enum value novu-agent-chat of the request property /////////
  request-property-enum-value-removed
- ○
  added the new novu-web-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-web-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-web-chat enum value to the request property /////////
  request-property-enum-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 16, 2026d7137c47680a33See the full diff
- ▲
  removed the enum value novu-web-chat of the request property ///////
  request-property-enum-value-removed
- ▲
  removed the enum value novu-web-chat of the request property ///////
  request-property-enum-value-removed
- ▲
  removed the enum value novu-web-chat of the request property /////////
  request-property-enum-value-removed
- ○
  added the new novu-agent-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-agent-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-agent-chat enum value to the request property /////////
  request-property-enum-value-added
Aug 4, 2026798a5a42d4c61See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Jul 31, 202647f16ff4d4273See the full diff
- ○
  added the new novu-web-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-web-chat enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new novu-web-chat enum value to the request property /////////
  request-property-enum-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 21, 20262e115ea8160c10See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new line enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new line enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new line enum value to the request property /////////
  request-property-enum-value-added
- ○
  added the new sendblue enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new sendblue enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new sendblue enum value to the request property /////////
  request-property-enum-value-added
- ○
  added the new webex-messaging enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new webex-messaging enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new webex-messaging enum value to the request property /////////
  request-property-enum-value-added

Full history