Webhook Connection
For instructions on configuring and running the BlueConic Webhook Connection, see the main Webook Connection page.
The Webhook Connection is a universal connection that can be used to send an HTTP request to an internal system (outgoing webhook) or to receive a request from an external system (incoming webhook). This connection is easy to integrate as a lot of third-party systems have API or webhook support.
The Webook Connection is great for implementing real-time use cases for systems that do not have an out-of-the-box, branded connection in BlueConic. If you do not have a real-time data need for your use case or you’re looking to send data in bulk, consider using a CSV-based connection (i.e., SFTP, S3, Google Cloud Storage, Azure, etc.) first.
Webhook Connection Use Cases
Typical use cases for the Webhook Connection can be broken down into outgoing versus incoming goals.
Outgoing webhook use cases:
Sending data from a submitted form dialogue to an email service provider (ESP).
Detecting cart abandonment and notifying an e-commerce system.
Updating contact information in a lead generation tool when a visitor reaches a paywall or triggers an exit intent.
Sending data to a marketing automation platform when a visitor uses a certain tool or feature on a channel.
Incoming webhook use cases:
Updating customer loyalty scores to use for website personalization.
Sending profile data updates from an ESP.
Deep dive on outgoing webhooks
For this section, we will be using a newsletter signup use case where BlueConic displays a form dialogue to prompt visitors to sign up for a newsletter with an email address and this email address is sent directly to an ESP upon submission.
Data flow
The data flow can be pictured above and described as:
Based on the visitor’s profile and the defined interactions (Listeners, Connections, Dialogues, etc.) in BlueConic, the decision engine determines which interactions need to be executed.
A newsletter sign-up dialogue is triggered. For example, showing a lightbox with a sign-up form.
The visitor enters their email address and submits the form. The form is configured to write the value from the input field to the “email” profile property.
BlueConic notifies the Webhook Connection that the property has changed. This happens because the Webhook Connection has the email profile property defined as the trigger property, so it will be notified when that property has changed. Relevant profile information is also sent along in this request.
The webhook service uses the configuration from the Webhook Connection and the profile to compose a request body and send it to the REST API.
The response from the ESP is used to update a profile property.
Data flow with a Timeline event
A webhook can also be triggered when a BlueConic Timeline event is added. For example, a cart abandonment event. The data flow for this scenario can be pictured above and described as:
The Abandoned Cart Tracker Connection is a batch connection that is typically configured to run frequently. In this connection, each run checks if there are new cart abandoners (typically defined as visitors who added products to their cart and then didn’t show any activity in the last X minutes). When an abandoned cart is detected, an abandonment timeline event is created.
BlueConic notifies the Webhook Connection. In this scenario, the Webhook Connection is configured to be called when an abandonment timeline event is added to a profile.
The Webhook Connection receives the profile and the added timeline event and translates the data to an API call to send to an ESP.
Building the outgoing request
When a webhook is triggered, any outgoing profile and timeline data must be translated into an HTTP request. This request consists of:
Component | Description |
Request URL | This can be entered in the “Request URL” input field.
|
Method | For retrieving data from the external system and storing the result in BlueConic, typically a GET is used. For updates, typically a POST or PUT is used. |
Headers | These are used to define an API key (or other authentication method, such as oAuth or tokens), set the content type, or to pass additional headers to make the request successful.
Note: In some cases, systems expect the API key in the querystring. |
Body | This is only relevant for PUT and POST requests containing the data to send to the external system, typically JSON. Mustache is used to format the message where profile property values and the triggering timeline event can be used to compose the message.
Note: Mustache doesn’t allow logic, so if statement or transforming options are not possible. |
Handling the outgoing request
The Webhook Connection supports the following content types:
application/json
application/vnd.api+json
application/vnd.unbounce.api.v0.4+json
application/xml
text/xml
application/vnd.unbounce.api.v0.4+xml
application/soap+xml
When the XML is received, it is translated to JSON. The received or translated JSON serves as input for the response mapping. Example expressions are:
$.id
Takes the “id” attribute from the root element
$.properties[?(@.id == 'emails')].values.length
Determines the number of values for id=”emails” in the properties
Note: Refer to this article for more information on JSON paths.
When a timeline event is defined as response mapping, the data will also be mapped using JSON path expressions. If the date is not defined in the mapping, the current date is used. If the ID is not defined in the mapping, a UUID is generated as an event ID.
When the outgoing request is successful, the “sent_to_system” profile property is appended with “webhook” as a value and the “sent_to_connection” profile property is appended with the UUID of the connection.
Deep dive on incoming webhooks
The incoming webhook is typically defined in an external system to update the profile in BlueConic or to add a timeline event.
Data flow
The data flow can be described as:
A subscriber is updated in the ESP and a webhook is defined to call on BlueConic to update the profile accordingly.
The REST endpoint takes the profile identifier from a query string to look up the matching profile. The profile and goal ID are forwarded to the Webhook Connection.
The Webhook Connection uses the configuration to determine how to handle the request. The updates are sent to the profile updater which writes it to the profile database.
Incoming webhook request handling
The REST endpoint will check if the webhook request is valid based on the scenarios described below:
If the API key setup is selected, the API key (generated by the Webhook Connection) must be either in the query string or the header (preferred).
If the oAuth setup is selected, the right token must be provided in the Authorization header.
If IP limitations are supplied, the request must come from an IP address that meets any of the defined IP ranges.
When none of these are the case, an unauthorized (401) error response is returned.
If requests are not sent as a POST request but are expected to be, a not found (404) error response is returned. This also occurs when no profile is found for the given identifier value.
The mapping that must be applied is determined based on the supplied goal ID. The mapping rules are processed where the value is expected to be a JSON path. For example, $.mykey would get the “mykey” attribute from the root element. Refer to this article for more information on JSON paths.
Note: When the output of the JSON path results in an object, it is stored as a stringified JSON.
For timeline imports, when no ID or date mapping is defined, BlueConic generates a value. Event properties are handled in the same way as profile properties.
Resolving errors
See Webhook Connections: Integration Tips for tips on resolving errors or problems in your webhooks. If you have additional questions you can't resolve, contact BlueConic Support at [email protected].