Custom events

A custom event is a signal your own systems send into Tarvent to say that a contact did something Tarvent cannot see for itself: finished onboarding, booked a demo, cancelled, returned a product, or passed a milestone in your app.

Tarvent records the event against that contact. You can then start a journey from it, or use it in a segment.

In this guide, you'll find:

1. How custom events work
2. Creating a custom event
3. Sending a custom event
4. Where you can use a custom event
5. Use cases and examples
6. Troubleshooting
7. FAQs

1 How custom events work

A custom event has a Name, an optional Description, and a Key that Tarvent generates for you. The key is what identifies the event when you send it, and it never changes.

A custom event carries no data of its own. It says only that this contact did this thing, at this time. If you need a value to travel with it, such as a plan name or an amount, write that value to a contact data field first, then send the event. The event is the signal; the data field holds the detail.

Note: Custom events are set up at the account level, so every audience in the account can use the same event.

2 Creating a custom event

Here are the steps:

1. Go to Account > Custom Events.
2. Click Add.
3. Enter a Name that describes what happened, such as Demo booked or Onboarding complete.
4. Optionally enter a Description, so your team knows when to send it.
5. Click Save.
6. Open the event again and copy its Key. You need the key to send the event.

Pro-tip: Name the event after the thing that happened, not after what you want Tarvent to do about it. Trial expired stays accurate when you later add a second journey that listens for it. Send win-back email does not.

You need the Custom events: View permission to see this page, and Custom events: Create to add one.

3 Sending a custom event

A custom event can only be sent by an API call, or from an iPaaS tool such as Zapier or Make. There are two ways to send one, and which you use depends on how your system identifies the contact.

From your own backend, by contact

Use this when your system knows the contact's Tarvent ID. Send a POST to https://api.tarvent.com/graphql with your API key in an x-api-key header and your account ID in an account header:

{
  "query": "mutation($id:String!,$key:String!){createContactCustomEvent(id:$id,key:$key)}",
  "variables": {
    "id": "CONTACT_ID",
    "key": "YOUR_EVENT_KEY"
  }
}

• id is the contact's ID, as a quoted string.
• key is the event's key, not its name. Sending the name answers with a not-found error.
• The API key needs the Audiences-Contacts: Create permission, and access to the contact's audience.

Note: This endpoint always answers 200. Success looks like {"data":{"createContactCustomEvent":true}}, so check the errors array in the response body rather than the status code.

From a web page or a tracked link, by tracking ID

Use this when the contact arrived from a Tarvent email or a tracked page, so you have their tracking ID (tvci) rather than their contact ID. Send a POST to https://tvtrk.io/v1/customevent with a Content-Type: application/json header:

{
  "Key": "YOUR_EVENT_KEY",
  "Tvci": "THE_CONTACTS_TRACKING_ID",
  "AccountId": "YOUR_ACCOUNT_ID"
}

• All three fields are required, and the key goes in the body rather than in the URL.
• Tvci is the tracking ID Tarvent puts on links in your emails and tracked pages. It identifies the contact, so this call needs no API key.
• A missing or unreadable Tvci, or an account ID that is not a number, answers 400 Bad Request.

Important: This endpoint is on Tarvent's tracking service, tvtrk.io, not on api.tarvent.com. The two are different hosts.

4 Where you can use a custom event

Once Tarvent has recorded an event against a contact, there are three places to use it:

• As a journey entry trigger. The Custom API event trigger starts a contact on a journey when the event arrives.
• In a segment. Build a segment of contacts who have or have not been sent a given custom event.
• In journey criteria. A journey step can check how many times a contact has been sent the event, so someone on their third purchase can be treated differently from someone on their first.

Note: Because the event carries no data of its own, a journey that branches on a value reads that value from a contact data field. Write the field first, then send the event, so the journey sees the new value and not the previous one.

5 Use cases and examples

• Onboarding complete: your app sends the event when a user finishes setup, which starts a "what's next" journey.
• Demo booked: your scheduling tool sends the event through Zapier, which stops the nurture journey and starts a pre-meeting sequence.
• Subscription cancelled: your billing system sends the event, which starts a win-back journey and takes the contact out of upsell segments.
• Milestone reached: your product sends the event each time a customer hits a usage milestone, and a journey checks the count to congratulate them on the fifth.

6 Troubleshooting

The journey did not start

• Check that the journey is started. A stopped journey discards the event rather than holding on to it.
• Check that you sent the key and not the event's name.
• Check the journey's Settings. If it is set to Run once per contact, a contact who has already been through it will not enter again.
• Check the trigger's Apply to which contacts criteria, and that the contact meets them.

The call failed

• The GraphQL endpoint always answers 200, so look at the errors array in the response body.
• A "Contact not found" error can mean the contact does not exist, or that your API key has no access to that contact's audience.

The journey sent the wrong email

• If the journey branches on a contact data field, write the field before sending the event. An event that arrives first is judged against the field's previous value.

7 FAQs