Skip to main content

​
Trigger Request

A trigger request is the initial step in handling a trigger event. It contains crucial details such as the template identifier, a list of subscribers who will receive the notification, the payload of the notification, and any overrides that need to be applied.

​
Trigger Endpoint

Upon sending the request to the event/trigger endpoint, a series of essential steps are initiated:
  1. Subscriber Mapping and Validation: The first step involves mapping and validating the subscribers for the specified event. This ensures that notifications are sent to the correct recipients.
  2. Workflow Validation: Following subscriber validation, the workflow associated with the event is validated. This validation process considers factors such as the active status to determine if it meets the necessary criteria for processing.
  3. Attachment Upload: Once the validation process is successfully completed, any attachments associated with the event are uploaded to the designated storage service.
  4. Event Queuing: The trigger event, now enriched with mapped subscribers and attachment links, is appended to the trigger event queue. This queuing mechanism optimizes response times, ensuring efficient event processing.

​
Trigger Event Processing

When an event is picked up by the trigger queue worker, the processing phase begins. Here’s what happens:
  • Subscriber Upsert: The worker validates the subscribers associated with the event and either creates or updates the subscriber with the information passed in the to object.
  • Context Upsert: When the trigger includes context entries with inline data objects, the worker creates missing contexts or replaces existing context data. String-only context references do not modify stored data. Inbox and other subscriber-facing APIs do not perform context data updates.
  • Notification Entity Creation: For each subscriber listed in the trigger event, a corresponding notification entity is created. This entity contains essential data related to the organization, template, subscriber, and event payload.
  • Job Creation: Based on the notification template’s defined steps, jobs are generated. These jobs are responsible for carrying out specific tasks related to the event notification. Additionally, the notification entity is updated with a “channels” field generated from these steps, indicating the communication channels through which notifications will be sent.

​
Jobs

Jobs play a crucial role in the trigger event lifecycle. They are created based on the steps outlined in the workflow.

​
Job Statuses

​
Frequently asked questions

An event is a request (for instance, an API call to /v1/events/trigger) that starts off an action in the Novu Workflow Engine. Events can make many different types of actions, including digests, delays, and sending notifications to various channels, as well as filters and user preference checks.
If a workflow is triggered to a subscriber, then it is billed as 1 event (one workflow run). If workflow is triggered to a group of 15 subscribers, then it is billed as 15 events.If a workflow is triggered to a topic, Novu fans out to matching topic subscriptions. You are billed for one workflow run per subscriber whose subscription passes Context matching and JSON Logic conditions, not for every subscriber on the topic. A topic with 100 subscriptions where only 20 pass creates 20 billable workflow runs. See Billing and workflow runs.
It depends on where the filter runs:
As a workflow triggered to one subscriber is billed as 1 event. if events are digested 15 times and a single digested notification is sent, then 15 events will be billed.
Repeated POST /v1/events/trigger requests that include the same Idempotency-Key header are halted at the API layer. Once the first request completes, duplicates return the cached response and do not queue the trigger again, so they count as one workflow run for billing. While the first request is still processing, duplicates receive a 409 Conflict response. See Idempotency for header requirements and retry behavior.
No. The optional transactionId field is returned for tracing and can be used to cancel a triggered event, but duplicate transactionId values are not deduplicated at the API layer the way Idempotency-Key is. Uniqueness is enforced during trigger processing, so retried or concurrent requests with the same transactionId do not get the same billing protection as an idempotency key. For safe retries and atomic deduplication, use an Idempotency-Key header on every trigger request.