Segment

Use a Segment Webhooks (Actions) destination to forward your Segment calls to JustAI. You create one destination with two mappings. The Identify mapping sends each Identify call that has a user ID to the Identify API, which creates or updates that person’s customer profile. The Track mapping sends each Track call to the Track API, which records it as a customer event. Segment’s Identify and Track calls already have the shape JustAI accepts, so you don’t reshape any fields. The destination forwards only the calls Segment receives after you turn it on, so also plan how to load existing customers.

Owner: Engineering

Before you begin

• You can add destinations in the Segment workspace whose source sends your Identify and Track calls.
• You have a JustAI API key for the environment you send to. See Create a key.
• You have your organization slug from your JustAI team. For a non-production environment, your JustAI team also gives you the environment’s path value, which replaces the slug, and its environment key for the X-JustAI-Environment header. To send to more than one environment, see Send to production and a staging environment.
• Your Segment calls carry the user ID you agreed to use in JustAI. See Identity and consent.

How the destination works

Each mapping uses Segment’s Send action. Its trigger decides which calls it sends, and its URL decides where they go.

Mapping	Trigger	URL
JustAI Identify	Event type is Identify, and the user ID exists	https://ingest.justwords.ai/api/identify/{org_slug}
JustAI Track	Event type is Track	https://ingest.justwords.ai/api/track/{org_slug}

With batching off, Segment sends one event per request as JSON. JustAI reads the fields it needs and ignores the rest. Page, Screen, Group, and Alias calls match neither trigger, so Segment doesn’t send them. Group calls must stay out of the Identify mapping. The Identify API doesn’t check the call type, so a Group call sent there would write the group’s traits onto the person’s profile.

Add the destination

1. In Segment, go to Connections > Catalog and search for Webhooks (Actions).

2. Select Webhooks (Actions), then select Configure Webhooks (Actions).

3. Choose the source that sends your Identify and Track calls.

4. Name the destination JustAI and create it.

   Leave the destination turned off until both mappings pass their tests.

Leave Shared Secret blank

Shared Secret, under Settings > Advanced Settings, is not your JustAI API key. Segment uses it only to sign each request with an X-Signature header, and JustAI doesn’t check that header. Leave the field blank, and don’t put your API key in it. JustAI authenticates each request with the API key in the X-Api-Key header that you add to each mapping.

Create the Identify mapping

1. On the destination’s Mappings tab, select New Mapping and choose the Send action.

2. In Define event trigger, set the trigger to Event type is Identify.

3. Add a second condition that the user ID exists.

   Segment then skips anonymous Identify calls, which the Identify API rejects.

4. Set the mapping fields to the values in the table below.

5. Test the mapping before you save it. See Test each mapping.

Field	Value
URL	https://ingest.justwords.ai/api/identify/{org_slug}
Method	POST
Headers	X-Api-Key with your API key as the value.
Data	Leave the default, which sends the entire event.
Enable Batching?	Off. Batch Size has no effect while batching is off.

Replace {org_slug} with your organization slug in lowercase, or with the environment’s path value for a non-production environment. Don’t end the URL with a slash. Keep Method at POST. The APIs don’t accept PUT or PATCH. Segment sets the JSON content type itself, so you don’t add a Content-Type header.

For a non-production environment, add a second header, X-JustAI-Environment, with the environment key from your JustAI team. Leave it out for production. A header with an empty value returns 400.

Fields JustAI reads from an Identify call

With Data at its default, Segment sends the whole Identify event. JustAI reads these fields and ignores the others, such as anonymousId, context, and integrations. To send only these fields, switch Data to Edit Object and add one key for each row.

Key	Segment event path	Rules
userId	$.userId	Required. A non-empty string. JustAI removes leading and trailing spaces.
traits	$.traits	Required. The whole traits object, with at least one trait. Each key becomes a profile attribute.
messageId	$.messageId	Optional. If Segment retries a call, JustAI applies it once.
timestamp	$.timestamp	Optional. When the change happened. JustAI keeps the newest value for each trait.

See Send customer profiles for how each update merges into the profile.

Create the Track mapping

1. On the Mappings tab, select New Mapping and choose the Send action.

2. In Define event trigger, set the trigger to Event type is Track.

3. Set the mapping fields to the values in the table below.

4. Test the mapping before you save it. See Test each mapping.

Field	Value
URL	https://ingest.justwords.ai/api/track/{org_slug}
Method	POST
Headers	X-Api-Key with your API key as the value. For a non-production environment, also add X-JustAI-Environment.
Data	Leave the default, which sends the entire event.
Enable Batching?	Off

Fields JustAI reads from a Track call

With Data at its default, Segment sends the whole Track event. To send only these fields, switch Data to Edit Object and add one key for each row.

Key	Segment event path	Rules
type	$.type	Required. Must be track. You can also set the static value track.
messageId	$.messageId	Required. The event’s unique ID. JustAI counts events that share a messageId once.
event	$.event	Required. The event name. Journeys match it exactly, including case.
timestamp	$.timestamp	Required. When the event happened.
userId	$.userId	Send userId, anonymousId, or both. Only events with a userId can start or advance journeys.
anonymousId	$.anonymousId	See userId.
properties	$.properties	Optional. The event’s properties object.
context	$.context	Optional. JustAI saves it with the event. Leave it out if you don’t want to send IP addresses and user agents to JustAI.

See Send customer events for how JustAI uses events in journeys.

Test each mapping

Test each mapping from the mapping editor before you turn it on. The test sends a real request to JustAI, so use a test user. A test Identify call creates or updates that user’s profile in the environment your API key belongs to.

1. In Define event trigger, select Load event from source to load a recent call of the mapping’s type. You can also select Generate sample event.

2. Change the user ID in the event to a test user, such as user-1234. For Identify, set a test email such as ada@example.com in the traits.

3. In Send test record, select Send test event.

   Segment shows JustAI’s response. The Identify API returns 200:

   Response

   {
     "success": true,
     "messageId": "msg-0001",
     "duplicate": false
   }

   The Track API returns 202:

   Response

   {
     "message_id": "msg-0002",
     "status": "accepted"
   }

4. If the response is an error, fix the mapping with Fix common errors and test again.

Turn on the mappings and the destination

1. In each mapping, select Save and enable.

   New mappings stay off until you turn them on.

2. On the Mappings tab, check that the Enabled toggle in the Status column is on for both mappings.

3. On the destination’s Settings tab, turn on the toggle at the top of the page to enable the destination.

Check your work

1. Open the destination’s Event Tester tab and choose Identify as the event type. The Event Tester tests only enabled mappings.

2. Load or write an Identify event for your test user, and select Send test event to destination.

   The test outcome shows one matched mapping and a 200 response from JustAI.

3. Repeat the test with a Track event for the same user.

   The test outcome shows one matched mapping and a 202 response.

4. Read the test user’s profile back with the Profiles API. The command uses the JUSTAI_ORG_SLUG, JUSTAI_ENVIRONMENT, and JUSTAI_API_KEY shell variables from Test your connection. For a non-production environment, JUSTAI_ORG_SLUG holds the environment’s path value and JUSTAI_ENVIRONMENT holds its environment key. For production, JUSTAI_ENVIRONMENT is empty, and curl leaves the header out.

   curl "https://ingest.justwords.ai/api/profiles/$JUSTAI_ORG_SLUG/user-1234" \
     -H "X-Api-Key: $JUSTAI_API_KEY" \
     -H "X-JustAI-Environment: $JUSTAI_ENVIRONMENT"

   The response is 200, and fields holds the traits from your test call. If a change isn’t there yet, wait a minute and read again. You can also search for user-1234 on Users in JustAI and open the row.

5. In JustAI, open Events > Custom events and find your test event’s name.

   New events can take time to appear. If an accepted event still doesn’t appear after you refresh, contact your JustAI team.

6. After live calls start to flow, open the destination’s Delivery Overview tab in Segment.

   Calls that JustAI accepted reach Successful delivery. Calls that JustAI rejected reach Failed delivery, grouped by status code. Page, Screen, Group, and Alias calls appear under Filtered at destination, because neither trigger matches them.

Segment retries temporary failures, such as a 503 response, for up to four hours. A 400, 401, 403, or 409 response means the call or the setup needs a fix. If Segment sends the same call again, it gets the same error.

Load existing customers

The destination forwards only the calls Segment receives after you turn it on. A customer who makes no Identify call after that has no profile in JustAI. Before launch, load your existing customers’ profiles once with Hightouch or the Identify API from your backend. If you need a customer-specific file import, confirm its availability and procedure with your JustAI team before building it. Use the same user ID that your Segment calls carry.

Fix common errors

Identify errors list each problem in an issues array. Track errors give the first problem in error.

Response	Cause	Fix
400, “At least one trait is required unless consent is provided”	An Identify call with no traits, such as analytics.identify("user-1234").	None. The call has nothing to save, and these failures are expected.
400, “Expected string, received null” at userId	An anonymous Identify call reached the Identify mapping.	Add the condition that the user ID exists to the Identify trigger.
400, Invalid literal value, expected "track"	A call that isn’t Track reached the Track mapping.	Set the Track trigger to Event type is Track.
400, “Expected object, received array”	Enable Batching? is on, so Segment sent a list of events.	Turn off Enable Batching? in the mapping.

For authentication and URL errors, such as 401, 403, 404, Invalid org slug, and Invalid environment, see Errors and retries.

Send to production and a staging environment

Send each JustAI environment its calls through its own Webhooks (Actions) destination.

• Create one destination for each JustAI environment, with its own Identify and Track mappings. Connect it to the Segment source whose calls belong in that environment, such as your staging source for a staging environment.
• In a non-production destination’s mappings, put the environment’s path value in the URLs in place of {org_slug}, for example https://ingest.justwords.ai/api/identify/acme_staging. Use an API key created in that environment, and add the X-JustAI-Environment header with the environment key.
• Name each destination after its environment, such as JustAI staging. A key, path value, and header that point to different environments return 403.

Avoid duplicate destinations

• Use Webhooks (Actions), not Webhooks (Classic). The Classic destination sends every call type to every URL you configure, so each JustAI endpoint receives calls it rejects. Classic also counts a message as delivered when any one URL accepts it, which hides those rejections.
• Send each Segment source to JustAI through one Identify mapping and one Track mapping for each JustAI environment. If two destinations forward the same source to the same environment, turn one off.

If you already send data to JustAI through an older setup

If your Segment workspace already has a JustAI destination, keep it running and don’t change its URL or settings. Create the new destination next to it, and turn the old one off only when your JustAI team tells you to.

Next steps

Send customer profilesHow Identify updates merge into a profile, and how to read a profile back.

Send customer eventsName events and send properties that journeys can use.

TroubleshootingFind the cause of a rejected call or a missing profile or event.