Webhook Connection

What:  The BlueConic Webhook connection allows you to pass BlueConic data to webhooks of external marketing automation platforms and import data returned. The Webhook connection also allows you to define incoming webhooks to BlueConic so external marketing automation platforms can pass data into BlueConic. 

About BlueConic: BlueConic is a Customer Data Platform that harnesses the data required to power the recognition of an individual at each interaction, and then synchronizes their intent across the marketing ecosystem. Click here to learn more.

Why: You want to connect BlueConic to a marketing platform for which there is no specific BlueConic connection. Many marketing platforms provide RESTful interfaces for other systems to interact with. BlueConic can leverage those interfaces to tie into the other systems using this generic webhook connection. Whenever the value of configured profile properties change in a profile, the BlueConic will trigger a request to the webhook and synchronize information. Or, your marketing platform can make webhook calls as events happen, to enrich the BlueConic profile.

 

Concepts

Profiles changes in BlueConic

As your visitors land on your channels and start interacting with them, their BlueConic profiles will get more rich over time. Handing off information to other martech systems helps you leverage this information or even enrich the BlueConic profile even further. The trick is to hand off the right information at the right time. This is why the webhook connection comes with triggers based on profile properties changing values: the hand-off will always happen at the right time for every visitor.

Events in your marketing platform

You existing martech system already tracks event for customers. If your marketing platform supports making webhook calls as it signals changes, it can hand off the information to a BlueConic webhook, and enrich BlueConic profiles in real time. This helps you leverage the information in other channels and across your other martech systems.

 

Configuring the connection

In the side bar on the left are a number of tabs. There is an About Webhook section and there are Requests sent by BlueConic and Requests sent to BlueConic goals. Goals are activated or deactivated with the checkbox in front of the name. Goals can be added by using the [Add goal] button at the bottom of the page. You can delete or copy goals by hovering over them and selecting the "x" respectively copy icon. 

Requests sent by BlueConic goals

Setting up a new "request sent by BlueConic" goal consists of only a couple of steps. Click Trigger Webhook request to start configuring. Simply follow the numbered configuration steps presented:

1. Select BlueConic segments

Here you can select one or more segments. Only visitors that are part of at least one of the segments can trigger the webhook. Typically one would create and select a segment here to filter for profiles that have values for the profile properties that will be used in the webhook. Select the segment "All Visitors" if you didn't have a specific segment in mind.

 

2. Select BlueConic triggers

The webhook connection will be triggered for a visitor when the value of one or more profile properties changes. Here you determine which profile properties will be monitored for value changes.

3. Configure Webhook request

This is where the actual magic happens; you will have to define how the connection will interact with the RESTful API of the external system. You will have to look up the exact technical details in the API documentation of your external system of choice. We have provided some examples to help you get started.

RESTful APIs by definition work based on web requests. So we have to specify the exact details of the web request that has to be sent:

Request URL
This is the URL of the Webhook as specified in the API documentation of the external system. Sometimes this URL has to contain profile information, in which case you can leverage Mustache tags to insert profile property values. Use the id of a profile property to identify it. For example, to insert the email address use {{{email.0}}}. Note how we use the triple braces {{{ ... }}} to prevent the default HTML escaping behavior of Mustache. Also, we use .0 as a safeguard to make sure we only pick the first value of the email profile property in case it contains multiple values.
Request method
The request method as specified in the API documentation of the external system. Pick one of GET, POST, PUT, PATCH or DELETE.
Request body
The GET method puts all of its parameters in the URL. All other methods use the body of the request to pass on parameters. Use Mustache tags to Construct a request body as described in the API documentation of the external system and use Mustache tags based on the id of profile properties to insert values.
Request headers
The request headers exist of name/value pair as described in the API documentation of your external system of choice. In the header value field you can use Mustache tags based on the id of profile properties to insert values.

 

4. Optionally map the Webhook response to BlueConic profile properties

After a successful Webhook request has been made, the external system might return a JSON response. You can create mapping rules to parse the Webhook response using JsonPath to obtain values and store those values in profile properties.

Click Add mapping to add more mapping rules. You can play around with JsonPath using the Online JsonPath Evaluator. The API documentation of your external system of choice should have example output to play around with.

 

5. Test Webhook

Once you have configured all settings of your connection, you can test the Webhook connection. Enter test values for all the trigger profile properties, then press the [Send test request button] to test your Webhook connection!

Click "Show request" and "Show response" to see what was sent and received from the Webhook.

 

Examples of outgoing webhooks

Here are a few examples for your convenience. Click a service to see its settings.

FullContact

Enrich your contact information using FullContact.

Request Method GET
Request URL https://api.fullcontact.com/v2/person.json?email={{{email.0}}}
Request Headers
Field Name Field Value
X-FullContact-APIKey your API key
Response Mapping
Response Field Profile Property
fullName Name
$.organizations[?(@.current)].name Company
$.organizations[?(@.current)].title Job Title
Slack

Have BlueConic chat you up using the Slack API!

Request Method POST
Request URL https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX
Request Body
{
    "text": "{{#surname}}{{firstname.0}} {{surname.0}}{{/surname}} visited the product overview!\n"
}
Request Headers
Field Name Field Value
Content-Type application/json

Requests sent to BlueConic goals

Setting up a new "request sent to BlueConic" goal consists of only a couple of steps. After setting up the BlueConic goal, you will have the information required to set up the request in the other system.

Follow the steps outlined below: 

1. Select BlueConic identifier

The external system that is going to send a request to BlueConic will have send a unique identifier to match with a BlueConic profile. Select the BlueConic profile property that will be used to make the match with the identifier sent.

Click the Save button to store the selection and generate the request URL information.

2. BlueConic request headers and API key

This step is purely informational. You will need the information displayed here to set up the request headers in the other system. We recommend using a request header to send the API key, as this is more secure than providing it in the URL of the request.

If the external system is going to send JSON data, use application/json as content type. If it is sending URL encoded form data, use application/x-www-form-urlencoded instead.

3. BlueConic request URL

This step is also purely informational, and helps in constructing the request URL for the other system. It displays URL parts labelled Goal address, Key (optional) and Matching. Use these three parts to construct a URL as follows:

  • If the external system will send the API key via request headers, append the parts Goal address and Matching to construct the complete URL.
  • If the external system cannot send the API key via request headers, append Goal address, Key (optional) and Matching to construct the complete URL.

Click Copy request URL to clipboard and paste it to the external system. The URL will look like this:

https://yourserver.blueconic.net/rest/custom/frontend/connection_webhook/update?itemId=123abc45-ab1c-1234-5678-1a12a12345a1&goalId=1234567890123_1234567890&apiKey=12ab3cd4e1a2bcde1abcd&property=email&email=

If the external system will send the API key via request header, remove the apiKey parameter from the request URL.

Note that the external system must provide and append the identifier (selected in step 1) to the request URL, so BlueConic can match the profile to update.

4. Map data from external system into BlueConic

Map the request data you want to import into BlueConic.

 

Enter the expression to select a field from the request data and select the BlueConic profile property it populates by entering a search term.

  • If the request data was sent as JSON, enter a JsonPath expression to select the field.
  • If the request data was sent as URL encoded form data, enter the parameter name to select the field.

Select how to import the data from the drop-down list:

  • Set
  • Set if empty
  • Add the data field to the list of existing values
  • Sum a number with the existing values (if the data field is a number)

5. Optional: Limit access by IP

Click Add IP range to restrict server access to the incoming requests. Servers whose IP address do not match any of the added IP ranges will be denied access to the BlueConic webhook.

Click Save on the top right corner of the screen to save your goal. 

 

The Webhook Connection is a standard plugin.