This guide summarizes the steps to start sending event data to Simon and setting up an event-triggered flow.

1. Sending event data

The Event Ingestion API provides a set of predefined event types, but in this guide we will focus on using custom events.

Event schema

This is an example of a full custom event:

{
   "partnerId": "[ REPLACE ME ]",
   "clientId": "92adbc3c-c22b-49bf-a9ae-11d9e8b3e6b4",
   "context": {
       "debug": true
   },
   "partnerSecret": "[ REPLACE ME ]",
   "sentAt": 1524776691259,
   "type": "track",
   "properties": {
       "eventName": "some_event",
       "properties":{
           "someProperty": "Some value"
       }
   },
   "traits": {
       "userId": "97980cfea0067",
       "email": "joe@smith.com"
   },
   "event": "custom"
}

You can read more about the different properties in the Events API documentation.

The custom event schema requires an eventName within the properties object. It accepts an arbitrary set of properties within properties.properties.

"properties": {
		"eventName": "some_event",
		"requiresIdentity": true,
		"properties": {
			"someProperty": "Some value"
			// add any additional properties here
		}
}

User identity information

The easiest way to handle identity is by passing in the email within the traits part of the payload.

"traits": {
       "userId": "97980cfea0067",
       "email": "joe@smith.com"
   }

If you provide email within traits for your events, you already have everything you need related to identity.

The custom event has an optional requiresIdentity parameter which defaults to true. If it’s set to false, events will be processed even if no email is supplied and no identify calls are found. This is a non-standard case that allows you to manage the identity within the event trigger query instead of the event itself.

You can also use the identify call to create a mapping between a clientId and a traits object containing an email address. clientId is as identifier for the user that persist for the duration of at least a session, analogous to cookie. userId is intended to reflect a more permanent user identifier from your system. The userId can be passed in as a clientId. The mapping created by identify will persist for 7 days.

API Environments

There are two environments, Staging and Production. You can use Staging to get the basics worked out, but will need to switch to Production to set up triggers for your events.

Debug flag

The debug flag means that the endpoint will return an error message with a reason if the payload does not meet the required schema. This flag is set within the context object and defaults to false.

Sending test events

You can generate a custom event by using curl to send an event payload to the endpoint. Make sure to enter your partnerId, partnerSecret, eventName, and any properties you want to pass along.

curl -H "Content-Type: application/json" -X POST -d '{ "partnerId": "[ REPLACE ME]", "clientId": "92adbc3c-c22b-49bf-a9ae-11d9e8b3e6b4", "context": { "debug": true }, "partnerSecret": "[ REPLACE ME ]", "sentAt": 1524776691259, "type": "track", "properties": { "eventName": "some_event", "properties":{ "someProperty": "Some value" } }, "traits": { "userId": "97980cfea0067", "email": "joe@smith.com" }, "event": "custom" }' https://simonsignal.com/http/v1/collect

2. Creating an event trigger

Once you have successfully sent a few sample events, you can start setting up an event trigger.

3. Setting up an event-triggered flow

After the event trigger is ready, you can create an event-triggered flow. To do so, create a flow, select Triggered category. Then pick When a contact triggers an event in the trigger configuration. You will see your existing event triggers in the dropdown under Configure Event Trigger.

Segment Membership Filters serve to limit the contacts that are messaged based on their Segment membership. By default, this is available as an exclusion filter. You can also set up experiments and branching.

An event-triggered flow will have access to the event data as content within the message. You can find out more about using event data as content in our guide to using event data in content and templates.

Once you launch an event-triggered flow, it will start running periodically and sending messages based on the events retrieved by the event trigger query. Any changes you commit to the query will automatically take effect for live flows.