Skip to main content
The Segment connector sends selected Novu webhook events to Segment’s HTTP API. Its transformation runs once per event and can map a Novu message object to a Segment Track call.
Outbound webhooks are available on Team and Enterprise plans.
This outbound connector sends Novu events to Segment. To send Segment events into Novu and trigger workflows, use the separate inbound Segment guide.

​
Prerequisites

  • A Segment source that accepts HTTP API calls
  • The source Write Key
  • Permission to manage webhook endpoints in the Novu environment
  • Novu event types whose payloads contain the fields your Segment call requires

​
Configuration

​
Transformation contract

Unlike batched storage and messaging connectors, Segment uses handler(webhook) for one webhook at a time. The input and output object contains: The webhook body wraps the resource in an envelope: webhook.payload.object is the resource type as a string, such as "message", and the resource itself is under webhook.payload.data.object. For message events, subscriberId and related message fields are therefore at webhook.payload.data.object. This example maps message events to Segment Track:
Segment rejects a Track call that has neither userId nor anonymousId, so the example cancels the delivery instead of sending an invalid call when an event carries no subscriber. Cancelled events are not retried. The resulting Track payload has this shape:
Subscribe this example only to message events that include data.object.subscriberId. For workflow events or other shapes, inspect the event type payload and map a valid Segment userId or anonymousId.

​
Configure in the Dashboard

1

​
Prepare the Segment source

Create or select a Segment source that supports the HTTP Tracking API. Copy its Write Key.
2

​
Add the endpoint

Open Webhooks in the Novu Dashboard, select Endpoints, click Add Endpoint, and choose .
3

​
Enter connection details

Enter the Write key.
4

​
Configure the transformation

Map each subscribed event shape, keep handler(webhook), and return the webhook object.
5

​
Select event types

Choose the event types to send. Add explicit transformation handling for every selected type.
6

​
Test the endpoint

Create the endpoint. In Testing, send an example for each selected event type. Confirm success in Logs, then verify the call and payload in the Segment source debugger.

​
Verify delivery

Open the Segment source debugger and confirm the Track call has the expected userId, event name, and properties. Compare it with the transformed request in the endpoint’s Logs tab.

​
Troubleshooting

  • Segment rejects authentication: Confirm the Write Key belongs to the intended source and environment.
  • userId is missing: Read it from webhook.payload.data.object.subscriberId for supported message events. Inspect the test payload before mapping other event types.
  • Track properties are empty: Preserve the original payload before assigning a new value to webhook.payload.
  • Only some events reach Segment: Confirm every required event type is selected and handled by the transformation.
  • Events appear in the wrong direction: This connector is Novu to Segment. Use the Segment Destination Functions guide for Segment to Novu.

​
Official references