How to setup outgoing webhook steps with response mapping

Introduced in  Gravity Flow v2.3, it is possible map the JSON values sent in the response to field values. This happens before the workflow moves on to the next step so you can define what happens next in the workflow depending on the response of an external API. For example, your webhook may request approval status from an external API, store the result in a field value and send a conditional notification based on the result.

Response Mapping Webhook Examples

APIs are a fundamental part of the open web which allow different web sites / servers to share data. Whether you own/manage an external application or you need to connect with or want to use one of many public APIs to return JSON responses, the possible uses of the response mapping feature of the outgoing webhook step are nearly endless. The examples provided below are meant to help you understand how to implement an outgoing webhook step with response mapping. The particular details of your form and API request/response format will require slight changes to fit your use case.

EU VAT Number Validation

vatlayer.com offers an API for checking that an EU VAT number is valid. They currently offer a free plan which you can use for testing. So, at any point in your workflow after the initial form submission, you can configure an Outgoing Webhook step to check that a VAT number is valid and then populate field values with the registered company name and address.

The following Outgoing Webook step will connect to the vatlayer API and lookup the VAT number in field ID 1.  The {:1} is the merge tag for field ID 1 and the API key for the service is hidden. The Response Field Values will look up the company_name and company_address values in the response and save them in the Company Name and Company Address form fields.

Here’s what the workflow entry detail page looks like after entering Amazon’s VAT number in a User Input step followed by the webhook step:

Automatic Translation of Entry Values

The  deepl.com API provides a translation API so we can use it to translate submitted values. Whereas the vatlayer API provides all of the response data at the top level of the JSON, deepl has a more complex structure so we need to drill down into the response to grab the right values.

Here’s an example response from the deepl API:

{ 
    "translations": [ 
        { "detected_source_language": "ES", "text": "Hello World!" } 
    ] 
}

In order to retrieve the translated text we need to use the key “translations\0\text” – we use the zero because the value for translations is an array and we need to target the first element in that array.

Postal Code / Zip Code Lookup

zippopotam.us offers a free API which lets you lookup full or partial zip codes / postal codes for over 60 countries. It returns multiple data points including the latitude / longitude including USA, Spain and Canada.

Here’s the response from the zippotam.us API:

In order to retrieve the place name we need to use the key “places\0\place name” – we use the zero because the value for places is an array and we need to target the first element in that array.

Our example form ( zippopotam-sample-form2.json – unzip and import the form) uses the {Country:2:value} merge tag for field ID 2 with the value modifier and the {ZipPost:1} merge tag for field ID 1 to build the outgoing URL.

The result lets you reduce the amount of data your customers have to enter without sacrificing on the key information you need to make business decisions. The result should be increased engagement in your form/workflow and a better business process that saves you time and money.

As you can see all this is configured with zero custom code. However, If the response from an API is more complex then you can use the  gravityflow_entry_webhook_response_mapping filter to customise it further.

Currency Conversion

Currency exchange APIs could be integrated to your workflow to allow you to store near real-time exchange rates at the time a form or step was completed. This example ( form currency-conversion-api.json  – unzip and import the form) shows how you can use merge tags within the response field key to dynamically select certain elements from the JSON response.

Here’s the response from currencylayer.com API. Notice that the key for the quotes require both the source and destination currency identifier.

If your form has the needed currency identifiers as field values you can use the merge tag to define which specific quote you would like to store.

When the webhook step is run the exchange rate is stored into a field for later calculations. Using  this snippet would also let you make calculations at the end of the webhook step for subsequent notifications to display.