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: The BlueConic customer data platform harnesses the data required to power the recognition of an individual at each interaction, and then synchronizes their intent across the marketing ecosystem.
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 use 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 use 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
Your 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 use 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 using the checkbox in front of the name. Click Add goal to add new goals. 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 a request to start configuring. Follow these numbered configuration steps:
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 visit of a profile on one of your channels causes a change in one of these profile properties, a request is sent directly for this profile. Here you determine which profile properties will be monitored for changes that are caused by a visit to one of your channels.
3. Select your authorization method.
Webhook requests typically require authorization, as dictated by the external system. You can configure the authorization for this webhook request via the 'Configure webhook request' in step 4 below or via OAuth 2.0 authorization.
- Select Add credentials via webhook request (step 4) for external systems that prefer credentials to be sent via headers or in the request URL.
- Alternatively, select OAuth 2.0 if the external system supports OAuth 2.0 authorization.
For OAuth2.0, BlueConic provides several ways to connect: authorization code flow, client credentials flow, and refresh token-based flow. The method depends on the security protocol used by the external system.
A. Authorization code flow
For web applications to server-side applications (the most generally used form), you can select the authorization code flow. Click the Open OAuth 2.0 configuration button that is revealed to open the authorizations settings pop-up. Enter the configuration options as defined by your external system of choice. Then click Authorize to authorize the connection.
Support for OAuth 2.0 is limited. Not all external systems are supported.
B. Client credentials flow
For machine-to-machine applications, you can use the client credentials flow. Click the Open OAuth 2.0 configuration button that is revealed to open authorization settings pop-up. Enter the configuration options as defined by your external system of choice. Machine-to-machine apps use the client credentials flow in which they pass along their client ID and client secret to authenticate themselves and get a token.
C. Refresh token-based flow
'OAuth 2.0: Refresh token-based flow' is mainly used for server-to-server authorization when the system offers a refresh token. Enter the configuration options as defined by your external system of choice. 
4. 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 use 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 consists of name/value pairs 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.
5. 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.
6. Test the 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 connection.
Examples of outgoing webhooks
Here are a few configuration examples to get you started. Click a service to see its settings.
- Quickbase
-
Connect BlueConic to your platform of choice via Quickbase.
Request Method POST Request URL The webhook URL generated by Quickbase. Something like: https://myApp.quickbase.com/db/bmehtzRequest Headers Field Name Field Value Content-Typeapplication/jsonRequest Body { "email_address": "{{email}}", "visits": "{{visits}}" }You can send as many profile properties as you want in this JSON format, and configure Quickbase (formerly Cloudpipes) to pick them up.The Quickbase (Cloudpipes) configuration will look something like this:
- 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:
- Select New applet from your user menu.
- Click +this.
- Search for the service Webhooks and click it.
- Click the trigger Receive a web request.
- Enter an event name, e.g. "bc_email_changed" and click Create trigger.
- Click +that.
- Search for the service Email and click it.
- Click Send me an email.
- Click Create action.
- Click Finish.
- Click the Webhooks logo in the top left of the applet.
- Click Settings.
- 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-52DjJOr7Request Headers Field Name Field Value Content-Typeapplication/jsonRequest 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 - 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-Typeapplication/jsonRequest 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 few 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 sent 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.
Additional URL options include:
- To allow the connection to create new BlueConic profiles when no match is found for the incoming webhook request, use the 'create profiles' option.
- If you cannot add the API key into a header as recommended above, you can add it to the URL (a less secure option).
- To set the legislation to GDPR instead of non, use the '&legislation=GDPR' string.
- If you have more than one domain group, you can send data to a domain group other than your default domain group by setting this option to that group's UUID.
- You can copy the full request link to the clipboard and paste the URL to the other system. The other system must provide and append an identifier so BlueConic can match a profile.
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.
Note that webhooks do not support date/time validation. If you configure mapping to a profile property of type Date Time, no value will be written to that profile property.
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.
Select 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.
Select Save in 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.