- 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
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
- Log in to your Segment account
- Navigate to Connections > Functions in the left sidebar
- Click New Function and select Destination
- 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
Code Explanation
Code Explanation
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 whensubscriberIdmatches
- Maps Segment traits (
onTrack:- Maps Segment
trackevents to Novu workflows usingEVENT_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 prioridentifyis useful for enrichment but not required for the trigger to succeed
- Maps Segment
3
Deploy the Function
- Click Save in the Function editor
- Enable the function by toggling it to Active
4
Connect the Function to a Source
- Go to Connections > Select your Source (for example, website or app)
- In the Destinations tab, click Add Destination
- Choose your Novu Destination Function from the list
- Click Connect. When prompted, enter your Novu API key in the
apiKeyfield - Save the configuration
5
Testing the Integration
Verify everything works:1. Send an identify event
1. Send an identify event
Example:Check Novu’s Subscribers list to confirm the subscriber appears with the mapped fields.
2. Send a track event
2. Send a track event
Example:Verify the
welcome workflow triggers in Novu’s Activity Feed.Troubleshooting
Troubleshooting
- 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
userIdis included in theidentifyevent. 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 includesuserId. - 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.
Additional Notes
Additional Notes
- Subscriber updates:
POST /v2/subscribersupdates an existing subscriber whensubscriberIdmatches, so eachidentifykeeps the profile current. - Expanding functionality: Add more event types (for example,
grouporpage) by defining additional handlers such asonGroupin the function.
identify and track events map into Novu subscribers and workflow triggers.