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

Profile 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

Open the Connections window, click Add connection and choose the Webhook connection to get started. In the side bar on the left are a number of tabs: About Webhook, as well as the Requests sent by BlueConic and Requests sent to BlueConic goals. Goals are activated or deactivated with the checkbox in front of the name. You can add goals 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" or the 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 configuration examples to get you started. Click a service to see its settings.

Cloudpipes

Connect BlueConic to your platform of choice via Cloudpipes!

Request Method POST
Request URL The webhook URL generated by Cloudpipes. Something like: https://www.cloudpipes.com/hooks/webhooks/2akks2q1zq8
Request Headers
Field Name Field Value
Content-Type application/json
Request Body
{
    "email_address": "{{email}}",
    "visits": "{{visits}}"
}
You can send as many profile properties as you want in this JSON format, and configure Cloudpipes to pick them up.

Cloudpipes configuration will look something like this:cp.png

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
IFTTT

Connect BlueConic to your platform of choice via IFTTT! Create a webhooks applet in IFTTT as follows:

  1. Select New applet from your user menu.
  2. Click +this
  3. Search for the service Webhooks and click it.
  4. Click the trigger Receive a web request
  5. Enter an event name, e.g. "bc_email_changed" and click Create trigger
  6. Click +that.
  7. Search for the service Email and click it.
  8. Click Send me an email.
  9. Click Create action
  10. Click Finish
  11. Click the Webhooks logo in the top left of the applet.
  12. Click Settings
  13. Copy the URL that looks like https://maker.ifttt.com/use/aJ2FeMm214Lj1wLsTT2-Mrs5hQT3_m1TFT-52DjJOr7 - you will need this to configure the webhook connection in BlueConic.

In BlueConic, create a webhook connection with these settings:

Request Method POST
Request URL The webhook URL generated by IFTTT. Something like: https://maker.ifttt.com/use/aJ2FeMm214Lj1wLsTT2-Mrs5hQT3_m1TFT-52DjJOr7
Request Headers
Field Name Field Value
Content-Type application/json
Request Body
{
    "value1": "{{email}}",
    "value2": "{{visits}}",
    "value3": "",
}
The IFTTT "Send me an email" webhook only allows for 3 values to be defined in the request body.
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
Shopify

Have BlueConic retrieve information via the Shopify API. For a more detailed description of how to set this up, see the Shopify Webhook article.

Request Method GET
Request URL https://yourserver.myshopify.com/admin/customers/search.json?limit=1&query=email:{{email}}&fields=id
Request Headers
Field Name Field Value
Authorization Basic [EncodedAPIKeyPassword] where EncodedAPIKeyPassword is the base64 encoded combination of the Spotify API key and the Spotify password separated by a colon.
E.g. Basic YXBpa2V5OnBhc3N3b3Jk
Zapier

Make BlueConic trigger a Zapier webhook Zap! Click Make a new Zap, select type Webhooks and select Catch Hook.

Request Method POST
Request URL In Zapier, click Set up webhook and copy the generated custom webhook URL to the clipboard. Something like: https://hooks.zapier.com/hooks/catch/1234567/f8f22dgg/
Request Headers
Field Name Field Value
Content-Type application/json
Request Body
{
    "email_address": "{{email}}",
    "number_of_visits": "{{visits}}"
}
You can send as many profile properties as you want in this JSON format, and configure the Zapier webhook Zap to pick them up.

 

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, because it's 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 the 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. 

 

Privacy management

Connections can be added to Objectives, allowing for privacy management of the information that is being picked up. A connection will only process the profiles of visitors who have consented to at least one of the objectives that the connection is linked to.

The Webhook Connection is a standard plugin.