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.
Why: For when 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 changes 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 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 events 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 systems.
Deep Dive into the Webhook Connection
For a technical deep dive into how Webhook Connections work in BlueConic, see the Webhook Connection Deep Dive article.
Configuring the connection
Open the Connections window, click Add connection, and choose the Webhook connection to get started. In the sidebar 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 with values for the profile properties used in the webhook. Select the segment "All Visitors" if you didn't have a specific segment in mind.
2. Select BlueConic triggers.
Select to trigger the webhook via one or more profile properties, e.g., if an email address is changed or added. Or select an event as a trigger and when this event occurs, the webhook will be triggered.
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 OAuth 2.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.
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 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. You can visit the Webhook Connection code examples article 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 |
|
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. Optional: 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.
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. Authentication method
Select how the other system can connect to this webhook goal, using a generated API key or OAuth 2.0 via a registered application added on the application page of the platform. The application should have read and write access for profile properties.
NOTE: All incoming request goals make use of the same authentication, so changing will effect all goals of this type.
3. BlueConic request URL
This step is purely informational and helps in constructing the request URL for the other system. It displays URL parts labeled 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:
Send requests by generating an access token of the external application if OAuth 2.0 method is selected in step 2 by adding an Authorization header having “bearer <token>” in the request.
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. Optional: Map incoming data from external system into BlueConic profile properties.
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: Import incoming data into BlueConic Timeline events.
Map request data fields to corresponding BlueConic Timeline events. You can either use JsonPath (e.g. '$.foo.bar' or '$..bar') or URL encoded (e.g. 'foo' or 'bar') expressions to match request data. Use “Current date” for a timestamp of the moment of import.
6. 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.