Managing Custom Events

On the project settings page, use the Manage Custom Events section to control how custom events flow into Iterable. You may find this functionality useful if using a platform like Segment to pass events into Iterable, and it’s passing in events that you don’t need.

In general, send events to Iterable only if they:

• Trigger a journey
• Are useful for segmentation purposes (now or in the future)

This includes events that are misnamed or no longer relevant. The main downside to sending all events is that it can clutter segmentation and other workspaces, making it harder for both experienced users and newcomers to find the fields that they're looking for. This can also have a performance impact, as it may take longer for Iterable to return all of the possible fields to you.

# Table of contents

# Event handling options

For each incoming event, Iterable can:

1. Save the event to a user's event history (useful for later segmentation)
2. Trigger a journey
3. Save the event to a user's event history and trigger a journey
4. Do nothing

The below table shows an example configuration where Iterable ignores all incoming error_app_crash events, saves quizCompleted events, and triggers one or more journeys with signUp events.

This example does not save signUp events to users' event histories.

# Event handling for newly encountered events

The Allow New Custom Events into the System toggle determines how an Iterable project deals with incoming custom events:

• When the toggle is on, the project saves all incoming events regardless of their event names. Additionally, it adds newly encountered events to the Existing Custom Events table (below the toggle), selecting both Allowed and Saved. This is the default behavior.
• When the toggle is off, the project only saves incoming events listed as Saved in the Existing Custom Events table (because they've been previously seen or you've manually added them).

In addition to this project setting, orgs that have the client-side API key permission, Event creation, must have this allowed in order to add new custom event definitions. If you want to add new custom event names to your project using a client-side API key, then you should also add this permission. To learn more about the Event creation API key setting, see our guide API Keys.

# Adding Events to the custom events list

In order to add a new event to the custom events table, navigate to the Existing Custom Events section and click New Custom Event.

Enter your desired event name in the Custom Event Name field that's presented to you, and click OK. Remember when entering the name that event names are case sensitive!

Notice how your new event is created with Allowed and Saved selected by default.

If you have already created a journey that triggers off of the event (like below), then the Triggers Journeys checkbox will be selected as well.

With your new event now established, navigate to the space to the far right of the event, and click Edit to adjust how it will be treated in your environment.

While editing, you can decide if you want to allow the event to pass through, and if so, if you want it to be saved to a user's event history.

Here are some additional considerations:

• You cannot save an event to a user's event history without also allowing the event
• You cannot trigger a journey from an event that is not allowed
• You cannot disallow an event that triggers a journey without first dropping it as the trigger to that journey
• An event cannot be deleted from the custom events table
• Allowing an event that was previously disallowed will not backfill or restore event history

# Updating custom events

When sending a custom event to Iterable via the POST /events/track API endpoint, an optional string id parameter may be passed. If an event exists with that id, the event will be updated. If no id is specified, a new id will automatically be generated and returned.

Sample response where an id of "12345" is passed in the track request:

{
    "msg": "Event with id: 12345 tracked.",
    "code": "Success",
    "params": {
        "id": "12345"
    }
}}

Sample response when no id is passed in the track request:

{
    "msg": "Event with id: 1397b147db9c41f187a39844beba9c tracked.",
    "code": "Success",
    "params": {
        "id": "1397b147db9c41f187a39844beba9c"
    }
}