Direct Webhook Integrations

This is a follow on guide for Webhook Integrations. if you haven't read it yet, start there.


This article will guide through configuring external business tools using Zapier, a third-party integration platform. For advanced webhook configurations, visit the Direct Webhook Integrations guide.

MailChimp is the system being integrated in this example, however, the same process applies to most other systems.

Following the example from the Webhooks Integration guide, the webhook for integrating MailChimp has been found and now it needs to be configured.

First, it is important to determine exactly what data is needed from MailChimp, otherwise the configuration will not return the correct results. In this case, details on every new MailChimp subscriber will be sent to Tonkean... directly from MailChimp.

NOTE: A direct webhook integration requires the external system to support Outgoing Webhooks. Google the name of the system with "webhooks" to confirm; i.e. MailChimp webhooks.

Alternately, the second part of this guide will detail coding services to directly send data to Tonkean.


Create Webhook in Tonkean

Once the intended system has been selected, give the integration a display name and click Create. This one is being called "Direct MailChimp."

In the following screen, copy the webhook URL. It will be needed it later.


Configure External System

The tool being integrated now needs to be configured to send data to Tonkean. Each tool has different elements for this, but, all have the same core principles. This is where the copied URL will be needed.

All that's needed to configure the external system or custom code is to send a JSON object to the webhook URL copied from the configuration screen above.

This can either be one JSON object or an array of JSON objects. No authentication headers are needed and the payload must be of "application/json" Content-Type.

NOTE: Tonkean accepts any valid JSON object.
NOTE: Many tools offer an "Outgoing Webhook" option that can be directly connected to Tonkean.

Go to the external system being integrated. In MailChimp, navigate to the List to integrate, select Settings > Webhooks, then Create New Webhook.

Paste the webhook URL copied from Tonkean in to the Callback URL field.

Click Save in MailChimp.


Sending the First Item to Tonkean

At least one item must be sent to the webhook URL, using POST, to complete configuration your webhook integration.

Call must contain a JSON object or an array of JSON objects, and must have a Content-Type of 'application/json'.

If a system is connected directly (as with the MailChimp example) you can expect that system to execute that process for you.

Once it's done, return to the Tonkean set up screen and click "I did it."

You should then see the following:


Map Between Your Object and a Tonkean Track:

To successfully represent a "MailChimp Subscriber" as a Track in Tonkean, the "id" and "title" fields need to be mapped.

All of the objects will be indexed into Tonkean. Mapping lets for Tonkean know what to display as the Track title and what identifier (id) to use to update existing items.

In this example, "id" is used for the id field path and "email" for the title field path:

Click Save to allow the configuration to kick in.


That's it!

Your app is now connected to Tonkean!

Any item received by this webhook will be indexed and can be used in Tonkean. The data can be accessed for Syncing Tracks, and creating Data Columns and Key Metrics.

Check out what you can do when you integrate your business tools into Tonkean.