Outbound webhooks are available on Team and Enterprise plans.
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 useshandler(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:
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:
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
2
Add the endpoint
Open Webhooks in the Novu Dashboard, select Endpoints, click Add Endpoint, and choose Segment.4
5
Select event types
Choose the event types to send. Add explicit transformation handling for every selected type.Verify delivery
Open the Segment source debugger and confirm the Track call has the expecteduserId, 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.
userIdis missing: Read it fromwebhook.payload.data.object.subscriberIdfor 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.