Skip to main content
This guide demonstrates how to use Segment’s Destination Functions to send user events and traits to Novu. You’ll learn how to:
  • Create a custom Segment destination for Novu
  • Map Segment identify calls to Novu subscribers
  • Trigger notification workflows from Segment track events
  • Handle errors and retry logic for reliable delivery
By the end, you’ll have a working integration that creates subscribers and triggers notification workflows in Novu based on Segment events.
Before you start, ensure you have:
  • A Segment account with access to Functions (check your workspace permissions)
  • A Novu account with an API key (find this in your Novu dashboard under Settings > API Keys)
1

Create a Destination Function in Segment

  1. Log in to your Segment account
  2. Navigate to Connections > Functions in the left sidebar
  3. Click New Function and select Destination
  4. Name your function (for example, Novu Destination) and click Create Function
2

Configure the Destination Function

The Destination Function will handle two key Segment event types:
  • identify: Creates or updates a subscriber in Novu
  • track: Triggers a notification workflow in Novu
Paste the following complete code into the Segment Function editor:
  • novuRequest: Shared helper for Novu API calls. Retries on server errors (5xx) and rate limits (429). Fails fast on other client errors so bad payloads are not retried forever.
  • onIdentify:
    • Maps Segment traits (firstName, lastName, email, phone, avatar) to Novu subscriber fields
    • Uses POST /v2/subscribers, which creates a subscriber or updates the existing one when subscriberId matches
  • onTrack:
    • Maps Segment track events to Novu workflows using EVENT_TO_WORKFLOW_MAPPINGS
    • Sends the event properties as the payload via POST /v1/events/trigger
    • Novu can create a subscriber just in time from to.subscriberId, so a prior identify is useful for enrichment but not required for the trigger to succeed
Update EVENT_TO_WORKFLOW_MAPPINGS with your Segment event names and corresponding Novu workflow identifiers. For EU accounts, set NOVU_API_BASE_URL to https://eu.api.novu.co.
3

Deploy the Function

  1. Click Save in the Function editor
  2. Enable the function by toggling it to Active
4

Connect the Function to a Source

  1. Go to Connections > Select your Source (for example, website or app)
  2. In the Destinations tab, click Add Destination
  3. Choose your Novu Destination Function from the list
  4. Click Connect. When prompted, enter your Novu API key in the apiKey field
  5. Save the configuration
5

Testing the Integration

Verify everything works:
Example:
Check Novu’s Subscribers list to confirm the subscriber appears with the mapped fields.
Example:
Verify the welcome workflow triggers in Novu’s Activity Feed.
Use Segment’s Debugger to monitor function calls and catch any errors.
  • 401 Unauthorized: Double-check your Novu API key in the function settings. The key must match your Novu environment (Development or Production) and region (US vs EU).
  • Subscriber not created: Ensure userId is included in the identify event. Traits must use the field names your function maps (firstName, lastName, email, and so on).
  • Workflow not triggering: Confirm the event name matches a key in EVENT_TO_WORKFLOW_MAPPINGS, the workflow exists and is active in Novu, and the track event includes userId.
  • 429 Too Many Requests: Segment will retry when the function throws RetryError. If you hit limits often, reduce event volume or upgrade your Novu plan. See Rate limiting.
  • Subscriber updates: POST /v2/subscribers updates an existing subscriber when subscriberId matches, so each identify keeps the profile current.
  • Expanding functionality: Add more event types (for example, group or page) by defining additional handlers such as onGroup in the function.
With this setup, Segment identify and track events map into Novu subscribers and workflow triggers.