Intercom: Webhook Setup Guide

[#1]

Intercom is a set of communication tools within a single platform that allows direct communication between businesses and their clients. Intercom has excellent developer documentation, which is what this connection and document is based off.

In this article:

Table of Contents Placeholder

Prerequisites

Before implementing this connector in Customer Data Hub it is strongly advised that you read and test the sections that are applicable to your business.

Authorization

Intercom adopts two authorisation methods; Access Tokens and OAuth. The following server-side integration with the Customer Data Hub uses an Access Token.

Configuring Intercom Access Token

When you create your token, it is likey you will need to extend its scope to leverage the request types for your business' needs. You can request this extension by asking the Intercom team.

To create your token:

1. Navigate to the Access Token section in Intercom
2. Request token
3. Edit scope (if applicable)
4. 

Customer Data Hub Configuration

Setting up your stream(s)

Skip this section if you are familiar with setting up streams.

I consider it best practice to always set up streams for your individual use cases or needs, unless you are sending all data to a vendor. This will allow you more granular control over the connections, as well as the ability to alter them in the future without affecting other requests. Having multiple streams and actions will increase maintenance, but may save complications down the line.

To do this:

1. Log in to Tealium Customer Data Hub
2. Navigate to Live Events under the Discover Tab
3. Click "+ Add Stream" and "Filter by Event Attribute"
4. 
5. Add a Title
6. Add the appropriate condition rules depending on your variables and Data Layer
7. 

Setting up a Webhook

For this example, I am going to create a Webhook that will pass a new user event. Intercom's API documentation on this type of request can be found here.

To build a custom webhook:

1. Log in to Tealium Customer Data Hub
2. Navigate to Connector Marketplace under Act tab
3. Search and select Webhook
4. Add Connector
5. Add a title
6. Leave BasicAuth fields blank
7. Navigate to the Actions tab
8. Choose the Send Custom Request Action and click "+ Create Action"
9. Give your Action a name
10. Choose the source of your data (stream)
11. Enter your API URL (check Intercom documentation, Users is https://api.intercom.io/users)
12. Leave the URL Parameters section blank
13. Add two Headers, both with custom fields, one with Map: applications/json To: Accept and another with Map: {{auth_template}} To: Authorization. The authorization mapping uses a template, which we will configure later. Make sure you put within {{}}.
14. Leave Cookies section blank
15. Select "application/json" in Body Content Type
16. Within the Body Data section, add a template mapping to Body. Make sure you put within {{}}.
17. Within the Template Variables section, add the mappings of your event level attributes to template endpoints. Make sure you select Event Attributes in this section if you are a AudienceStream customer as this is an EventStream setup. Leave names in the "To:" fields without {{}}
18. Under Templates add two templates, one for the Authorization and one for the Body. Use the exact same names as created in previous sections. In the Authorization template add the Access Token you generated in Intercom after "Bearer ". For the Body template follow Intercom documentation along with Trimou Template Engine Guide. Make sure you use "" as its use changes depending on variable type (integers, strings etc.). You will have to nest your Template Variables mapped in previous step within {{}} as a minimum.
    
19. Save Action and Webhook
20. Save/Publish
21. Test the Webhook using Trace

With everything configured you can now test the setup with Trace.

If successful, you will see a successful Action Processed in Trace and the data within Intercom.

If unsuccessful follow the errors on the Intercom Webhook connector in the My Connectors section under Act tab. I would also recommend testing with Postman at this stage with your exact webhook configuration. Ensure you replace the mappings with actual values.