# Segment Webhooks

Aggregations.io enables you to monitor and utilize your Segment data in real time. When combined with the Grafana plugin, you can visualize and alert on your Segment analytics events with ease.

# Prerequisites

To set up this integration you'll need to first:

  1. Set up an ingest using the Array of JSON Objects schema.
  2. Create an API Key with Write permissions to use with this integration. We'd recommend creating a dedicated Org-Wide API Key.
  3. A segment account with incoming data sources.

# Setting up the destination

# 1 - Add a new Webhooks (Actions) destination

Navigate to your organization's Destinations page on Segment and choose Add Destination

Search for Webhooks and select it.

Click the Add Destination button

# 2 - Select data source

Choose the relevant data source whose events you want to utilize in Aggregations.io.

# 3 - Name your Destination

Give your destination a useful name like Aggregations.io

If you are creating multiple destinations for different sources but want to utilize the same settings, you can choose to copy them at this step.

# 4 - Mappings

Click on the Mappings tab and choose New Mapping

Select Send to set up the action.

# 5 - Mappings, Selecting events

Select your filter settings, if you want to restrict the data flowing into Aggregations.io. Segment has made this functionality very powerful, see their guide here to understand the full capability.

For our example, we know we want to count just Track and Page events, so that's what we select.

# 6 - Mappings, Test event

Scroll to section (2) and either load a test event from your Segment setup or just load a sample event.

# 7 - Mappings, Selecting mappings

Scroll to section (3) and you'll fill in the following:

  • URL should be your POST URL (something like https://ingest.aggregations.io/[ID])
  • Method should be POST
  • Batch Size should be ~ 250. Depending on the average size of your payload, you may want to increase or decrease this to ensure your payloads are not too large. Check out the Ingest API limits.
  • Inside Headers you will add your API Key in the left box and x-api-token in the right
  • Data should be left as Select Object and $event (unless you know you want to modify your payloads)
  • Enable Batching? should be Yes

# 8 - Mapping, Test Mapping

Assuming the above steps are filled in, your Test Mapping button should be enabled. Click it!

If not, review the steps above to ensure you have mapped all the fields and you have a test event set up.

If your test succeeds, you should get back an empty payload.

If there is an error, see below.

# Enabling the destination

It is important to ensure both the destination and mapping are enabled within Segment.

  • Enable the Destination on the Settings tab
  • Enable the Mapping on the Mappings tab

# Timestamps

When setting up an ingestion to use with Segment, you may want to rely on one of Segment's timestamps instead of the Use Ingest Timestamp option.

You'll want to be careful to choose on of Segment's non-client-authoratitive timestamps like receivedAt in order to ensure it's a correct format. See Segment's docs on timestamps here.

To utilize receivedAt when setting up your ingest:

  • Choose Use Custom Timestamp Property
  • Set Timestamp Format to ISO 8601 String
  • Set Timestamp Path to @.receivedAt

# Troubleshooting

# Error Codes

See the Ingest Docs for common errors ingesting events.

# Reversed headers

If you receive an error indicating No Authorization Header it may indicate you've reversed the API Key value and header name

# Extra headers

If you accidentally add an extra blank header in the mapping you may receive an error is not a legal HTTP header name, simply delete the extraneous header.