Segment

The Segment integration forwards Segment payloads into a GraphJSON collection named segment. It is useful when Segment already receives your product events and you want to analyze the same stream in GraphJSON.

Set up GraphJSON#

1. Open Integrations.
2. Choose Segment.
3. Select Create it now if the segment collection does not exist.
4. Copy the API key shown by the setup page.

GraphJSON creates the collection before you configure the destination.

Security: Treat the API key as a secret. Store it only in Segment’s protected destination settings, not in event properties or client-side analytics code.

Configure Segment#

Configure a webhook-style destination that sends JSON events to:

https://api.graphjson.com/api/integrations/segment

The GraphJSON receiver reads the API key as the Basic Authentication username. Follow the setup values shown in the GraphJSON dashboard if they differ, because Segment’s destination interface can change.

Segment’s current Extensible Webhooks destination can send real-time event payloads to custom HTTP endpoints. See Segment’s Extensible Webhooks catalog entry for provider-side details.

Verify the connection#

Send a test track event from a Segment source, then open the GraphJSON segment collection and select Samples.

Confirm:

• the event timestamp matches the source payload
• the Segment event name is present
• identity fields such as userId or anonymousId are present
• nested properties appear as flattened dot-separated keys

If the event is missing, check Segment’s delivery log and the HTTP status returned by the destination before changing GraphJSON filters.

Query Segment events#

Start by inspecting the stored shape:

SELECT
  timestamp,
  json
FROM segment
ORDER BY timestamp DESC
LIMIT 20

Then extract fields using the exact names shown in Samples. Segment schemas differ by source and destination configuration, so avoid assuming a property path before you inspect a real event.

Control schema drift#

Segment payloads can include context, integrations, traits, and large property sets. Create a short data contract for the fields your GraphJSON metrics depend on:

event
userId or anonymousId
properties.account_id
properties.plan
properties.amount

Keep those types consistent at the Segment source. Provider forwarding cannot repair inconsistent application instrumentation.

Preserve source identity#

Segment payloads can contain messageId, userId, and anonymousId.

• use messageId when investigating or deduplicating a retried delivery
• use userId only when it is a stable application identifier
• preserve anonymousId for pre-authenticated journeys
• do not use context.ip as a durable person identifier

Confirm the actual paths in Samples. Destination actions and source libraries can produce different envelopes.

For metrics that must deduplicate:

SELECT
  JSONExtractString(json, 'event') AS event,
  uniqExact(JSONExtractString(json, 'messageId')) AS unique_messages
FROM segment
WHERE JSONExtractString(json, 'messageId') != ''
GROUP BY event
ORDER BY unique_messages DESC

Do not use this pattern when messageId is absent or reused incorrectly by a custom source.

Monitor delivery#

Keep a Segment-side owner for:

• destination enablement
• delivery logs and response statuses
• retry or discard behavior
• source schema changes
• write-key rotation

In GraphJSON, monitor hourly event volume, last observed timestamp, unknown event names, missing identity fields, and schema-version adoption.

If GraphJSON volume drops:

1. confirm the Segment source is still receiving events
2. inspect destination deliveries and HTTP statuses
3. check that the destination is enabled for the intended source
4. confirm Basic Authentication uses the active GraphJSON key
5. send one approved test event
6. compare its Segment messageId with GraphJSON Samples

Do not change dashboard filters before checking the provider delivery record.

Separate test and production#

Prefer separate Segment sources or destinations and separate GraphJSON workspaces for strict isolation.

At minimum, include an application-derived environment field and exclude non-production events from production metrics. A browser-provided environment value alone is not a security boundary.

Reconnect or change sources#

Treat a source or destination replacement as a cutover:

1. record the last messageId from the old path
2. configure the new destination
3. send a canary
4. inspect field paths and timestamp
5. watch for overlap and duplicate messages
6. update dependent queries when the envelope changed
7. disable the old destination only after validation

Enabling a destination does not guarantee historical Segment messages will be replayed. For older history, use a controlled Segment export and the migration workflow.

Disconnect#

Remove or disable the destination in Segment first, then delete the GraphJSON integration or segment collection if you no longer need the stored events.

Important: Deleting the collection removes its events and cannot be undone. Export anything you must retain first.

Use Operate managed integrations for shared monitoring, incident, reconnection, and retirement procedures.