Webhooks: Data Exchange via 3rd Party URLs

  • Updated

  • 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 decision trees, we will walk through how to build a simple tree that asks for a USA zip code and then shows the city and state for that zip code inside the tree.

    Try this demo tree in the Zingtree Gallery 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

    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.

    Adding the Webhook:

    1. Go to Account Settings > My Apps.
    2. Click the Add Webhook button under My Apps.
    3. Enter a name for the webhook, and the URL as shown:
      The URL is:

       

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

      #zip# will receive the zip code variable entered by the end-user.

    4. Click Add Webhook. This makes the hook available to your trees.

    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 different node, select the webhook call.
    3. Under Apps and Webhooks, select Add App.2022-04-11_15-03-47.png
    4. Select Webhook: Zip Lookup from the Webook to Call drop-down menu2022-04-11_15-06-35.png
    5. 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 tree:

    &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 tree session.

    Bearer Token

    For Authorization Type = Bearer

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

    &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.


  • Our larger corporate clients have asked us for a way to be able 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 decision trees, we will walk through how to build a simple tree that asks for a USA zip code and then shows the city and state for that zip code inside the tree.

    Try this demo tree in the Zingtree Gallery 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

    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.

    Adding the Webhook:

    1. Go to Account > My Apps.
    2. Click the Webhook button under My Apps.
    3. Enter a name for the webhook, and the URL as shown:The URL is: 
       https://zingtree.com/apps/webhook/filters/zippopotamus.php?zip=#zip#

      #zip# will receive the zip code variable entered by the end-user.

    4. Click Add Webhook. This makes the hook available to your trees.

    Calling the Webhook when a node is visited:

    1. Go to Overview, and edit the node you want to trigger the webhook call.
    2. Under Apps/Webhooks, select Webhook: Zip Lookup from the Call App or Webhook drop-down.2022-04-11_14-56-44.png
    3. Save Changes when you are finished. 

    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 tree:

    &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 tree session.

    Bearer Token

    For Authorization Type = Bearer

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

    &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.


  • Throughout 2022 Zingtree will be upgrading customers to our new faster and more modern user experience! Here's how to tell which experience your Zingtree Authors are currently using.

    Log in to your Zingtree Author account and navigate to My Trees. How does your current My Trees page look?

    Zingtree Classic

    2022-02-25_12-24-51.png

    New User Experience

    mceclip0.png

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request

Submit a request