You may have a need to exchange Zingtree data with other applications. Some customers want to send data from a Zingtree session to another application or include data from another application in Zingtree.

Zingtree’s data exchange feature makes use of Webhooks with JSON formatted data. In fact, a lot of the tools we utilize work the same way.

Here’s an Example

To demonstrate how to send and receive data from your workflows, we will walk through how to build a simple workflow that asks for a USA zip code and then shows the city and state for that zip code inside the tree.

Try this demo workflow here.

We will send data to a custom webhook we built, which takes a parameter of a zip code. It returns a JSON structure with the city and state info.  Here’s an example of the webhook in use:

http://zingtree.com/apps/webhook/filters/zippopotamus.php?zip=94960

If you click the link above, you’ll see these results:

{"zip":"94960","state":"California","state_abbreviation":"CA","city":"San Anselmo"}

The PHP source code for the webhook URL is here.

The variables #city#, #state# and #state_abbreviation# will now be usable by Zingtree. So to show the city, just enter #city# into the content area of any node.

Webhooks Process Overview

Here’s a summary of how this works:

1. Add the webhook to your organization’s apps. 
2. Include a call to the webhook in a node. When the node is visited, the call is executed.
3. Any JSON variables returned by the call become Zingtree variables.

How to add Webhooks and other Apps

From the Apps & Integrations menu, choose My Apps:

This page lists all of the Apps you have presently installed. You can edit, duplicate, or delete any of them from the list. In the Uses column, you can easily see how many workflows an individual App is being used. Click on the number in the Uses column to see which workflows are using that App.

Adding a new App

Click the Install App button. You'll then see this screen:

Choose the Webhook button to add a new Webhook. You'll see these options.

1. Enter a name for the webhook, and the URL as shown:
   The URL in this example is:

    https://zingtree.com/apps/webhook/filters/zippopotamus.php?zip=#zip#

   #zip# will receive the zip code variable entered by the end user. For example, you have a data entry field prior in your workflow where the end-user enters a zip code and the variable for that field is zip.

2. Webhook Headers: Here you can add any standard or non-standard request, response, or payload header (as defined here) and assign static values to those headers as shown in the placeholder text. Each header and value needs to be added in its own line.
3. Click Add Webhook. This makes the hook available to your trees.
4. Webhooks are accessed from the server side. Architecturally, that means client endpoints need to be publicly accessible somehow: direct or some sort of proxy.

Calling the Webhook when a node is visited

1. Use a data entry field with the variable name #zip# to collect the zip code. Please note that the variable name must be an exact match to the variable name in the webhook in order for data to be passed in. 
2. On a following node where you want to call the webhook go to the Apps and Webhooks section and select Add App.
3. Select Webhook: Zip Lookup from the Webook to Call drop-down menu
4. Use the #city# and #state# variables in the content area to surface the information from the Webhook.  
    

Universal Parameters

Every call to the webhook URL you provide always includes the following parameters:

• node_id
• session_id

Adding Security/Authorization

You can add an extra layer of security to your webhooks by passing an authorization token into the URL that launches your tree. The token is passed back to the webhook URL in the HTTP header.

To send the authorization token MYTOKEN, add this to the URL that launches the workflow:

&auth_token=MYTOKEN

To check the token in your webhook, look at the X-Auth-Token value in the HTTP header.

Please note: The auth_token remains the same for the entire workflow session.

Bearer Token

For Authorization Type = Bearer

To send the Bearer token MYTOKEN, add this to the URL that launches the workflow:

&auth_token=bearer:MYTOKEN

To check the token in your webhook, look at the ‘Authorization: Bearer MYTOKEN‘ value in the HTTP header.

Credits

The demo uses the free zippopotam.us postal code lookup service.

• Webhooks: Troubleshooting
• Data Entry Field Variables: Adding Input Forms to your workflows
• Webhooks: Library