# 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.

error

We recommend using our official Segment Destination, but this documentation may be helpful for setting up webhooks on other platforms.

# Prerequisites

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

Set up an ingest using the Array of JSON Objects schema.
Create an API Key with Write permissions to use with this integration. We'd recommend creating a dedicated Org-Wide API Key.
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

You can also navigate directly to the destination page by replacing your {WORKSPACE} in the url below https://app.segment.com/{WORKSPACE}/destinations/catalog/actions-webhook

# 2 - Select data source

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

If you have multiple sources, you'll need to follow this guide for each. You can opt to utilize the same ingestion & API keys across multiple Segment sources, or create separate ones for isolation. In most cases, reuse makes sense for consistency and simplicity.

# 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.