Using Webhooks

Webhook Integrations allow Tonkean to connect and sync data with any third-party online application that uses APIs or webhooks. Tonkean supports thousands of third-party tools and, in most cases, Webhook Integrations are available for tools not supported natively.

There are two types of webhooks:

1. Inbound Webhook = This is when a 3rd party application will SEND data to Tonkean

2. Outgoing Webhook = This is when Tonkean will SEND data to the 3rd party application

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

 

Creating an Inbound Webhook

Before creating a Webhook in Tonkean, it’s important to know if the application you’re trying to connect with supports Webhooks. Searching their Knowledge base or reading through their API documentation will usually tell you. When you confirm the application does, the first step is to create the endpoint URL that data will send to Tonkean.

We’ll be using Mailchimp as our Webhook application in this example.

1. Click on Data Sources on the top menu

2. Click on the green Add Data Source

3. Search for the Application you want to connect with. Connections that have an italicized “(Custom Source)” on them can be connected via webhooks

4. If your application doesn’t show up in the list, you’ll see the option New Custom Source which you can use to setup your Webhook

Note that we have many Native Integrations where you can simply use your Username/Password or an API key to connect. Visit our Native Integrations guide for setup instructions for those.

5. Once the intended system has been selected, give the integration a display name and click Create. 

6. In the following screen, copy the webhook URL. This is the Endpoint URL where Mailchimp will send data to Tonkean. You’ll need to give this URL to Mailchimp.

---

Configure External Application

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

Important Technical details: Tonkean accepts any valid JSON object or an array of JSON objects. No authentication headers are needed. Only “application/json” Content-Type.

Many tools offer an "Outgoing Webhooks" option that can be directly connected to Tonkean. For Mailchimp, navigate to the List where you want data sent to Tonkean. Click on Settings > Webhooks then “Create New Webhook”

Paste the webhook URL copied from Tonkean into the Callback URL field.

Select all of the update data you want Mailchimp to send Tonkean. When done click Save in MailChimp.

---

 

Sending the Data to Tonkean

At least one item must be sent to the webhook URL, using POST, to complete the configuration of your webhook integration. This will ensure that the correct connection has been made between the two systems and will give you a preview of the exact data that’ll be sent.

Once it's done, return to the Tonkean setup screen and click "I did it." You should then be taken to a new screen where you’ll need to configure a few fields. You can also preview the JSON we got which will show you the data Mailchimp sent over.

To successfully represent a "MailChimp Subscriber" as an Item in Tonkean, the "id" and "title" fields need to be mapped. Normally, the ID will be the unique ID that the 3rd party application (in this case, Mailchimp) sends over. The Title is what the item will be called, and viewable by the user, within Tonkean. Make this something that’s unique, but also gives you enough information on each piece of data that comes through (examples: name, email address, company name, etc.).

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

Click Save to allow the configuration to kick in.

Your app is now connected to Tonkean!

Any data received by this webhook will be indexed and can be used in Tonkean. The data can be accessed for utilizing Triggers/Actions in your Module along with creating Fields and Key Metrics.

Adding Fields To Tonkean From Your Webhook

Now that data is being sent to Tonkean from your 3rd party application, you can select fields in your Module that you can use as Triggers and Actions. It’s the same process as other native integrations. You can view more about Mapping Fields in this article.

 

Creating an Outbound Webhook

While the above explained how you can GET data from other applications so you can Trigger and take action within Tonkean, you also have the ability to PUSH (or send) data from Tonkean to other applications.

Each Module has the ability to create multiple outbound webhooks.

1. Navigate to the specific Module that you want to send data from

2. Within your Module workflow, click on the Settings cog in the top right

3. Click on Outgoing Webhooks

4. Click on Create new webhook

Choose a name and select the activities that should trigger your webhook. This means that every time one of these actions within Tonkean happens, Tonkean will send the data to this 3rd party application.

In the Webhook URL enter your Webhook/API URL for Tonkean to call. You will need to get this from your 3rd party application.

You Webhook URL must conform to the following:

1. Accept HTTP POST

2. Accept JSON Content-Type

3. Require no authentication

Click on the "Example" link to see a JSON example of what will be sent. This is what format the JSON should look like. You can click “Test” which will send the data, and if accepted you’ll get a positive confirmation message. 

When you have successfully tested, click Create

Now, every time an activity on that specific Module triggers (i.e. an Item was created), Tonkean will send to the URL you specified a JSON of the Item data and a log of the changes that triggered the event.