Skip to main content
Novu supports the following webhook event types:
  • Email events: Events when Novu receives inbound mail on a verified domain with a webhook route.
  • Message events: Events about message delivery status changes.
  • Preference event: Event about subscriber preference changes.
  • Workflow events: Events about workflow creation, updates, and deletions.
Each event includes detailed information about the affected resource and the changes that occurred.
Every event payload is published in the OpenAPI specification under x-webhooks. The Event Catalog on the Webhooks page renders those schemas, so it always matches what Novu sends.

Event envelope

Every webhook body uses the same envelope. The resource itself is under data.object.

Email events

  • email.received: Triggered when Novu receives an inbound email that matches an Inbound Email Webhook route on a verified domain. The payload includes normalized mail content (from, to, subject, text, html, headers, attachments, threading fields) plus domain and route metadata. When the matched route address is only in the SMTP envelope (a BCC recipient not present in to or cc), it appears in mail.bcc and to is left unchanged; the field is omitted otherwise. Download files from each attachment’s url before expiresAt. See Attachments.
email.received is for user mail received on your domain. It is not the same as delivery or engagement events from your outbound email provider - see Email Activity Tracking for those.

Inbound email payload

data.object contains domain, route, and mail. Each attachment has the following fields.

Message events

  • message.archived: This webhook is triggered when a subscriber archives a message. The payload contains the details of the event.
  • message.deleted: This webhook is triggered when a message is deleted. The payload contains the details of the event.
  • message.delivered: This webhook is triggered when a message delivery provider acknowledged the message delivery to the end receiving client. The payload contains the details of the event.
  • message.failed: This webhook is triggered when Novu tries to send the message to the delivery provider and it got failed. The payload contains the details of the event.
  • message.read: This webhook is triggered when a message has been read by the subscriber. The payload contains the details of the event.
  • message.seen: This webhook is triggered when a subscriber opens a message. The payload contains the details of the event.
  • message.sent: This webhook is triggered when Novu sends the message to the delivery provider. The payload contains the details of the event.
  • message.snoozed: This webhook is triggered when a message is snoozed by the subscriber. The payload contains the details of the event.
  • message.unarchived: This webhook is triggered when an archived message is unarchived. The payload contains the details of the event.
  • message.unread: This webhook is triggered when a message is unread or marked as unread by the subscriber. The payload contains the details of the event.
  • message.unsnoozed: This webhook is triggered when a message is unsnoozed by a subscriber. The payload contains the details of the event.
Email and push activity-tracking events use these same message.* types. The status mapping is in Activity tracking.

Message payload

All message events share the same data.object shape. message.sent and message.failed can also include an error object next to object. Chat providers report a send failure on message.sent, so treat error as meaningful on both events.
Secrets on channelData such as token are redacted before delivery.

Activity tracking

Email activity tracking and push activity tracking are delivered as message.* webhooks with the message payload. Novu also sends message.sent when it hands the message to the provider, and message.failed when that handoff fails. Those events are independent of activity tracking. Email activity tracking sends message.sent again when the normalized status is sent. Resend (email.sent) and Amazon SES (Send) report that status. SendGrid and Mailgun do not.
data.object is the message record loaded when the event arrived. seen, read, deliveredAt, and status still hold the values from before this event. Use type as the activity signal.

Email

Email activity tracking is available on Novu Cloud and Enterprise self-hosted. Provider events are normalized to the statuses in Event semantics, then mapped: clicked is written to the activity feed and sets read and seen on the message. delayed, complaint, and unsubscribed are written to the activity feed and leave the message unchanged. bounced, rejected, blocked, and dropped send message.failed and leave status on the message unchanged. The activity feed keeps the specific status. Any other normalized status, including spam and deferred, is not sent as a webhook.

Push

Push events are the eventType values forwarded to the activity track API. Novu matches the event when eventId is the __nvMessageId from the notification. See Push activity tracking. clicked and dismissed both send message.read.

Preference event

  • preference.updated: This webhook is triggered when a subscriber preference is updated. The payload contains the details of the event.

Preference payload

data contains the updated preference under object, plus the subscriberId it belongs to. The nested workflow object has the following fields.

Workflow events

  • workflow.created: This webhook is triggered when a workflow is created. The payload contains the details of the event.
  • workflow.deleted: This webhook is triggered when a workflow is deleted. The payload contains the details of the event.
  • workflow.published: This webhook is triggered when a workflow event occurs, that is when a workflow is synced from dev to prod environment. The payload contains the details of the event.
  • workflow.updated: This webhook is triggered when a workflow is updated. The payload contains the details of the event.

Workflow payload

Workflow events carry one of two shapes, so check the table below before parsing. The workflow response is the same shape the Workflows API returns, including workflowId, name, description, active, tags, steps, origin, status, severity, preferences, issues, createdAt, and updatedAt. The stored workflow is the raw persisted document, so it uses internal field names rather than API names.
On workflow.updated, previousObject may also include userPreferences and defaultPreferences when the update went through a workflow patch. Treat both fields as optional.