Streams enable you to send data to mutual customers from your web services in real time.

Building a Stream

Segment empowers companies of all sizes to use their customer data to grow their business. In addition to more than 180 analytics and marketing tools that receive data from Segment, a growing number of source partners — including Salesforce, Twilio, Stripe, Zendesk, and more — send data into Segment for their customers to use in any destination. By creating a Segment data stream, you’ll enable customers to use data from your tool wherever it’s most useful to them.

Understanding the integration

To complete the source setup flow, the customer will need to input the Segment write key for this source in your integrations settings UI. This will enable your tool to route customer data back to Segment correctly.

Customers can find their write key in the source settings and regenerate it as needed.

The Segment Spec

To learn about the semantics of the five supported API calls, and the semantic event names and properties Segment recognizes, read the Segment Spec.

The Spec is a critical component of preserving semantics between sources and destinations. If you break the Spec, you are breaking the promise of Segment, which is grounds for removal from the catalog.

If your tool requires specific data points not included in the Spec, get in touch.

Sending data

To send events to Segment, you should post events directly to the Segment HTTP API. You may use any server-side Segment library to do so. The HTTP API has a couple of basic requirements.

Beyond the Spec, there are a few additional requirements for partner Streams.

userId

Each call sent to Segment must contain a userId, which allows Segment to identify unique users. This value should be stored by your tool when you receive an event from Segment.

For example, you might receive an Identify call with a userId and traits about that user. If that user is sent an email and opens that email, you would want to send an Email Opened event back to Segment with that same userId . The userId should be part of the call body as a top-level object.

If you have your own unique identifier you use in your tool, Segment recommends passing that along as a context property in the event for QA purposes. For example:

    "type": "track",
    "userId": "abc",
    "traits": {
        "email": "customer@company.com"
     }
     "context": {
       "yourToolId": "123"
     },

integration

Each call should contain a context.integration object in the call body that identifies your tool (for example where the call is coming from). Use the slugified name for your tool, and 1.0.0 as the initial version — if you’re unsure of your integration slug, contact Segment support. Once Streams are supported in the Developer Center, this will be rendered for you and will be validated as part of the QA process.

This should be part of the context top-level object and will look like:

    "context": {
      "integration": {
        "name": "your-tool",
        "version": "1.0.0"
      }
    }

writeKey

Each call must contain a writeKey. Segment provides this writeKey to customers in the settings panel for each of their sources. As mentioned in the setup flow description above, customers will need to save their Segment write key in your UI in order to authenticate calls being made by your tool.

The write key is required in the header of every call to identify the customer whose data Segment receives. See the authentication section of the HTTP API docs for more detail. If you do not include a customer write key in the call header, Segment will reject track calls from your tool.

Rate limits and batching

There is no hard rate limit at which point Segment will drop your data. However, to avoid processing delays, Segment asks partners to send requests at a maximum rate of 50 requests per second.

If you want to batch requests to the HTTP endpoint, refer to the batching documentation. The suggested maximum rate includes any batch requests.

Regional Segment

Segment offers customers the option to lead on data residency by providing regional infrastructure in both Europe and the United States.

Segment recommends that you let users choose which Segment endpoint to send data to for the given writeKey from your system.

Process

Plan

If you have not already, review your timeline and resourcing plan. Include which events your source will be sending to Segment to ensure they are properly specified. Segment onboards new sources as quickly as possible, but you should only commence building once you receive approval from Segment.

Build

All three of these steps should be completed before you begin testing:

• Following the guidelines above, format your outbound webhook to Segment’s HTTP API.
• Add a field in your settings UI where customers can input their Segment write key.
• Write docs for your source — you’ll need to have separate docs for your source (example) and integration.

Testing

1. If you don’t have a test account up and running already, create a free Segment account.
2. Set up a source depending on the kinds of events you need to test. For example, if your source sends mobile event data, you’ll need to instrument a Segment mobile SDK into a demo app.
3. Copy the Segment write key for this source into your integration settings and save.
4. Take actions that generate the events your source should be sending. For example, if your source is sending email data to Segment, you should:
   1. Create an email campaign that includes one hyperlink and an unsubscribe option.
   2. Send this to yourself.
   3. When you receive the email:
      1. Open the email
      2. Click the link
      3. Unsubscribe
5. Check your Segment debugger for events. If the Source is working correctly, you should see a live incoming event stream of events (such as Email Delivered , Email Opened , Email Link Clicked , Unsubscribe ).