Signal Connector Integration with Webhooks Guide

This document is a guide to using Certain Signal Connector to integrate with other applications by using Webhooks. This document does not cover the ‘Advanced Webhooks’ product. Advanced Webhooks includes everything described here plus the use of nested JSON. See the separate guide to integrations using that product. Signal Connector also integrates with Marketo, Eloqua, and Salesforce. See separate guides.

Certain Signal Connector for Webhooks is automatically included with Certain Platform for new customers.

Certain Signal Connector for Webhooks integrates with other applications by using Webhooks.

If you’re interested in adding this or any other Signal Connector integration to your instance of Certain, email help@certain.com. Include your account name. Include the Signal Connector integration(s) you’re interested in.

1. What is Signal Connector? How does it work?

2. Prerequisites

Data-Flow Considerations
Credentials in Target Application

3. Overview of Setup Steps

4. Setting up Tags

What Are Tags?
Setting Tags Up for an Account
Applying Tags in an Account
Applying Tags in an Event

5. Opening Certain Signal Connector

6. Setting up a Connection

What are Connections?
Adding a Connection

7. Setting Up Flows

What is a “Flow”?
The Flow List
Configuring a Flow

8. Flow Data Source

Available sources
Activate for

9. Flow Filters

10. Flow Destination

Setting up a Destination
Mappings

11. Metrics Dashboard

Account Insights

12. The Retry Queue

13. Replaying a Flow

What is Signal Connector? How does it work?

Certain Signal Connector processes data from your events in real-time. Certain Signal Connector passes that data from Certain Platform to your target third-party application. The target third-party application could be any app with webhook integration. Examples include Slack or Google Forms.

This real-time integration empowers sales and marketing teams to take intelligent, prompt action on the right event data.

Almost everything is set up at the account level. Signal Connector processes information from the events in your account.

Event-level information depends on the custom tags you attach to data such as Registration Statuses. This guide explains the role of custom tags.

Important: Signal Connector processes outbound information. Signal Connector processes information from Certain. Signal Connector sends that information to your target application.

Prerequisites

Data-Flow Considerations

Do you capture data in registration questions that will be synced to the third-party app to which you are integrating?
If so, apply tags to those questions. See Registration Questions.
Do you have different data mappings based on registration status or attendee type?
If so, apply tags to those items. See Applying Tags in an Event.

Credentials in Target Application

To set up a Connection in Signal Connector, the administrator of your target third-party application will need to provide you with the information described under ‘Adding a Connection’.

For example, if your chosen Authentication Method there is OAuth2, then the administrator must create an OAuth2 app in that system. The administrator must provide Endpoint, Client Id, and Client Secret.

Overview of Setup Steps

| Step | Page | |---|---| | On Certain Platform 1. Add tags in the account | Setting Tags Up for an Account | | 2. Apply those tags | Applying Tags in an Account | | On Certain Signal Connector | | | 3. Add a Connection | Setting up a Connection | | 4. Configure a Flow | Setting Up Flows |

Setting up Tags

What Are Tags?

Tags identify event-level data using labels you set at the account level.

You can apply those tags to generic items in events. You can apply tags especially to custom registration statuses and custom registration properties for use in Certain Signal Connector.

Tags can be used for other purposes as well. This guide does not cover other purposes.

For example, your events may have several custom registration statuses in addition to the standard ones.

You can apply the same Tags to more than one status. You can also give each status its own Tag.

When you set up a Flow in Certain Signal Connector to send data to your target application when an attendee’s Registration Status changes, you specify the tags applicable to those statuses. You do not specify the statuses themselves.

That means the flow can apply to any event in your account.

Setting Tags Up for an Account

1. As an Administrator, go to Account Settings > Management > Tags. 2. Enter a Name and a Label for the tag. 3. Select the Object(s) to which the tag can apply. For example, ‘Registration Statuses’ and/or ‘Custom Registration Properties’. 4. Click Add. 5. Repeat as required for as many tags as you need. 6. Important: Add enough tags to apply to all of the following that you will use in flows. a. Registration Statuses b. Custom Registration Properties 7. Also add enough tags to apply to all of the following that you will use in filters for flows. a. Attendee Types b. Events

Applying Tags in an Account

In each event from which you want information to flow through Certain Signal Connector, apply tags to relevant information. Relevant information includes Registration Statuses and Registration Custom Properties.

You can also tag Attendee Types and Events. You can use those tags to filter registration records by attendee type or event. See Flow Filters.

Default Registration Statuses

These apply to all events. An Administrator applies the tags at the account level.

1. Go to Account Settings > Management > Registration Statuses. 2. Select one or more Tags for each status.

Important: Even if you don’t use any standard registration statuses, best practice is to set up tags for all of them. It is essential to tag at least the ‘New’ status. Certain uses “behind the scenes” when first processing each registration.

If you do use standard reg statuses, it’s essential that you tag them all. Tagging standard registration statuses enables use of those statuses in Flows configured in Signal Connector. See page 9.

Applying Tags in an Event

Custom Registration Statuses

1. If any of the Flows you configure in Signal Connector will watch or activate for changes of Registration Status, then in each event go to Plan > Event Setup > Custom Statuses. 2. Select at least one tag for each status.

Custom Registration Properties

If any of the Flows you configure in Signal Connector will watch or activate for Custom Reg Properties:

1. In each event, go to Plan > Configure. 2. Under Custom Registration Properties, select at least one tag for each custom reg property in the event.

Standard Registration Properties (Automatic)

These tags are set up automatically. The tag names are identical to the properties themselves.

Complete, Badge Printed, On To Do List, Invoice Generated, and Test.

You only see these tags in Signal Connector. You can activate Flows for them in Signal Connector. See Activate for …

There is nothing to edit on Certain Platform.

Attendee Types

(Optional—for use with filters—see Flow Filters.)

1. In each event, go to Plan > Event Setup > Attendee Types.

2. Select one or more Tags for each attendee type on which you may wish to filter registrations.

See Filters on see Flow Filters.

Events

(Optional—for use with filters—see Flow Filters.)

1. In each event that you may wish to include in a filter, for example, to ensure that only registrations for that event are passed to your target application: 2. Go to Plan > Event Setup > Details. 3. Select one or more Tags for the event.

Registration Questions

(Optional—for use with mapping Certain fields to fields your target application—see Mappings.)

1. In each event in which you use registration questions to capture data from attendees and wish to pass those answers and/or questions to your target application:

2. Go to Plan > Event Setup > Questions.

3. Select just one Tag for each question.

Selecting more could result in duplicate data in your target application.

Opening Certain Signal Connector

When Signal Connector is activated for your account, the Account Settings > Implementation menu is available to Administrators. The menu includes an extra option:

Signal Connector Real-Time Data Integration

Click that link to open Certain Signal Connector in a separate window. Signal Connector runs separately from Certain Platform.

Note: To return from Signal Connector to Certain Platform at any time, click the control shown in the guide.

Setting up a Connection

What are Connections?

A Connection in Certain Signal Connector specifies how to connect to your target application.

You can have multiple connections, including to other third-party applications. Marketo, Eloqua, and Salesforce are covered in separate guides.

Each Flow requires a Connection. Multiple flows may use the same Connection.

You can set up a Connection before configuring your first Flow. You can also set up a Connection while configuring a Flow.

This guide assumes you are setting up the Connection first.

Adding a Connection

As an Administrator, you may set up one or more Connections for your account.

You need to set up Connections only once. You then use the Connections in Flows you set up.

1. Go to Account Settings > Implementation > Signal Connector Real-Time Data Integration. 2. As noted above, Certain Signal Connector opens in a separate window. 3. Click Connections in the left navigation panel. 4. Click Add A Connection in the Connection List page that opens. 5. Enter the details in the Connection Setup screen that opens.

Target: Use the pre-selected value, Webhook
Connection Name: Enter a name of your own choice. This could be just the name of the application with which you are integrating, for example
Authentication Type: Select the authentication type to be used from the options available.
Your choice determines the other fields displayed for you to complete.

Basic Authentication

URL: The endpoint to which Signal Connector must send data.
Content Type: Select one of the two options.
application/json
x-www-form-urlencoded
Request Method: Select ‘POST’ or (if appropriate) ‘GET’.
User Name: The user in the target system must have the necessary minimum permissions in that system if any are required.
Password: That user’s password.

Open / No Auth

The lowest level of security.

As for Basic Authentication above, but without a User Name or Password.

API Key / Token

API Key / Token: To be provided by the administrator of your target application.

OAuth2

All these values must be provided by the administrator of your target application.

Grant Type: Select ‘Client Credentials’ or ‘Authorization Code’
Client Id and Client Secret: These two long strings of characters are unique to the OAuth2 app your administrator has set up.
This matches the explanation under ‘Credentials …’ on page 2.
Authorization URL
Access Token URL
Refresh Token URL
Scope: Depending on your target app, your requirements, and your security policies, this might be blank, a keyword, or a URL.
For example, it might be blank, a keyword, or a URL.
Test Connection URL
Is this a primary connection — Leave this check box clear.
It’s displayed for all connections.
It is only relevant to Eloqua, Marketo and Salesforce integrations requiring backwards compatibility.

6. Click Save & Test. 7. If the test is successful, click Close. 8. If the test is not successful, check that the values in step 5 are all correct.

Setting Up Flows

What is a “Flow”?

A flow manages the flow of data from Certain to your target application.

You create Flows from the landing page in Signal Connector. See Configuring a Flow below.

You may configure several flows for an account. Those flows might all use the same Connection.

You only need to configure a flow once at the account level.

When a flow is complete, it starts picking up data for each event in that account within about a minute.

The minute’s delay exists because Signal Connector runs independently from Certain Platform.

If you edit a flow, then the same slight delay occurs before that change takes effect in the processing of the registrations.

The Flow List

As an Administrator in Certain Platform, go to Account Settings > Implementation > Signal Connector Real-Time Data Integration.

Certain Signal Connector opens in a separate browser window.

The main screen in Signal Connector is the Flow List. The Flow List lists all flows.

The Status column shows whether a flow is completely set up.

The Active column shows whether the flow is running.

Click the toggle button to change a flow from Active to Inactive, or vice versa.

Configuring a Flow

Click ADD A FLOW to start setting up a new flow.

The configuration consists of:

Name
‘Live’ or ‘Test’ status
See immediately below.
Source: What information the Flow will look for. Source also determines what the Flow will activate for in your events.
See Flow Data Source.
Filters: Optional filters to narrow down that information.
See Flow Filters.
Destination: Where and how that information goes into your target application.
See Flow Destination.

‘Live’ or ‘Test’

The Live toggle switch determines whether your Flow is Live or Test.

A Live Flow picks up all live registrations in live events. A Live Flow ignores test registrations. This includes test registrations in live events.

A Test Flow picks up all test registrations. Test registrations include all registrations in test events. It also includes registrations marked as ‘Test’ in live events.

Best Practice: Set a new flow up as Test—and test it—before setting it to Live.

Flow Data Source

Next, specify the Source of data for the flow. Optionally apply Flow Filters.

The Source of a Flow is what the Flow will watch for in your data in Certain. The Source also defines when the Flow activates based on that data.

For example, the flow might watch for any change to a Registration Status. The flow activates if an attendee’s status has changed to a status tagged as ‘Registered’.

Available sources

You set a flow to watch for any one of the following:

Registration Create Update: When a registration is created or updated.
Registration Status Change: When a registration’s status changes.
Session Registration Status Change: When a registration’s session registration status changes.

Note: You can always save an incomplete Flow and complete it later. After you complete the Flow, it starts picking up data after the usual minute’s delay.

Activate for …

Choose what the flow should activate for by selecting one or more tags in each appropriate object’s dropdown list.

As shown in the screenshot, you can activate for tags applied to Registration Statuses and/or Registration Properties.

Other options may be added depending on what the Flow is watching for:

If the Flow is watching for Registration Status Change, you must activate for Registration Statuses.
If the Flow is watching for Session Registration Status Change, you must activate for Session Registration Statuses.
If the Flow is watching for Event Create Update, you must activate for Event Statuses.

The tags available for selection are those set up for that object. See Setting up Tags.

For example, the tags for Registration Statuses include Registration Status tags. You can apply those tags to:

standard registration statuses at the account level (see Applying Tags in an Event)
custom registration statuses at the event level (see Applying Tags in an Event)

Flow Filters

You can filter the data going into a flow by selecting fields in any of these three filter types:

Event fields
Profile fields
Attendee Type tags

The flow includes a registration only if it meets the rule(s) specified in the filter.

Event

Available fields:

standard event fields (e.g., Event Code)
custom event fields
event tags

Profile

Available fields:

standard profile fields (e.g., Position)
custom profile fields

Attendee Type Tags

Available fields:

tags that can be applied to Attendee Types

Note: For custom fields you can only select “enumerated” questions. Enumerated questions have pre-configured answers. Enumerated question types are Select, Multi-select, Checkbox, or Radio.

Flow Destination

Select Webhooks from the integrations set up by Certain for your account.

You may have this and others to choose from.

Setting up a Destination

1. Give the Destination a Name of your choice.

2. Select the Connection to use.

Note: You can instead click New Connection to add a connection. The process to set one up is the same as described on Setting up a Connection.

3. Select Webhook as the Action for this connection.

4. Select or add the mappings to use. See Mappings.

Mappings

You can select or set up a set of mappings.

You can have two mappings:

one for the Payload
one for the Http Header (if required)

The setup process is the same for each.

A mapping specifies how each target field in your third-party application matches a source field in Certain.

Select a mapping from the drop-down list.

If nobody has set any mappings up yet, or you need something other than one of the existing mappings, click New Mapping to add one.

New Mapping setup steps

1. Give the mapping a name of your choice.

Best Practice: For multiple mappings used for different flows, make the names self-explanatory.
For example, ‘Lead Mapping’ and ‘Contact Mapping’

2. Obtain a sample JSON from the source.

For example:

{
  "FirstName": "Joe",
  "Surname": "Citizen",
  "Email": "jcitizen@example.com",
  "RegCode": "123-456789-4321",
  "EventName": "Summer Product Launch",
  "Status": "Registered"
}

3. For each of the target fields you identify in that JSON, such as FirstName in the example above:

a. Enter the name of that target field and Click Add

b. Click to select the “source” field in Certain that matches that target field.

In this example, the target field in your target application is ‘First Name’.
You select the source field “FirstName” in Certain.
The value of that Certain field populates the “First Name” field in your target application.

4. The Certain fields you can choose from as the source of the data going into each target field will include some of the following, depending on what your flow will activate for.

Profile Standard Fields
Profile Custom Fields
Registration Standard Fields
Registration Custom Question Tags
One field for the question.
One field for its answer.
See Applying Tags in an Event about not using the same tag for more than one question.
Registration Standard Properties
Account Standard Fields (Account Code)
Event Standard Fields (e.g., Event Code and Event Name)
Event Custom Fields
Flow Fields (Flow Name)
Macros (e.g., Current Date)

5. Note: You can concatenate multiple source fields for the same target field. You can also type fixed text.

For example, for target field ‘Title’ you could choose source fields ‘Position’ and ‘Organization’. The fields are separated by two spaces and “@”.

6. To make a target field a required field, select the checkbox next to it.

7. If a required field is missing, there’ll be a validation error when the flow tries to update your target application.

This is not normally fixable.
This would not go into The Retry Queue.

8. To delete a source field, click the x after its label.

4. In the second column you can select a transformation option for each field.

The default of no selection sends the data unchanged.
The options are:
lower case
Proper Case
UPPER CASE
Trim (This removes extra spaces.)
You can select more than one transformation for a field.
For example, you could change it to Proper Case and trim it.

5. Continue adding more target/source field pairs as necessary.

6. If you’ve selected a mapping then two other buttons are enabled.

Edit Mapping
Preview Mapping

7. Save the mapping.

Metrics Dashboard

To see the statistics available in Signal Connector, click Metrics in the left navigation panel when looking at flows.

The choices in the new navigation panel depend on the flows and their targets.

The first one will be Insights.

Other links might be, for example, Webhook Posts. All work in the same way as Account Insights.

Account Insights

Select whether you want to see Live Flows or Test Flows.

Select the period for which you want to see the data. For example, for the last 15 minutes, 1 hour, or 4 hours, or a number of days.

There are three tabs: Summary, Troubleshooting, and Activity Feed.

Summary tab

This is the default tab on the Insights page.

The figures shown depend on the flows and actions.

For some figures you can click the number to drill down further. For example, click Unique Registrations to see the registrations processed by any flows in your selected time frame.

You can filter or search for records after you drill down.

For example, filter on an Event Code to see only the registrations in that event.

The figures listed below are shown.

These figures are for the whole account. The figures include all events and registrations. The figures include all flows in your account. Some flows might not be Webhooks integrations.

For each figure, you can click the number to drill down to details.

Changes Processed: The number of registrations processed.
It increments each time a registration is created or updated in Certain.
It increments each time that registration is then processed by a flow in Signal Connector.
Note: This will often include the same registration more than once.
Creating a registration and then updating it twice would total three “changes”.
Unique Registrations: The number of registrations processed. It counts any single registration only once.
This is likely the most relevant figure on the page.
It’s likely to be lower than Changes Processed.
If Joe Citizen’s registration was processed three times, then Changes Processed would have increased by 3.
Unique Registrations would have increased by only 1 because all changes were for the same registration.
Actions Triggered: The number of actions triggered by flows.
If you have one flow with one action, Actions Triggered could match Changes Processed.
The number of actions triggered increases as the number of flows and actions increases.
Actions Not Triggered: Only displayed if registrations were processed by flows without actions being triggered.
This could be caused by a registration having an untagged status.
Active Flows: The number of flows actually processing registrations during the selected period.
This is not related to whether the flow is shown as “Active” or “Inactive” on the Flow List.
Leads Created: The number of leads created in your target application by flows.
Leads Updated: The number of leads updated in your target application by flows.
Registration Activity in Certain: Overview information.
Processing Status: A pie chart comparing the numbers of failures and successes.
Drilling down into failures provides a high-level view for troubleshooting.
The drill down can show why an action failed.
If the failure can be addressed, then you can expedite the fix in Signal Connector.
To expedite the fix, go back to Flows and click Retry in the left navigation panel. See Retry Queue.

Troubleshooting tab

The second tab on the Insights page shows information useful for troubleshooting.

For example, if some registrations are not processed because a Registration Status isn’t tagged, this gives the chance to rectify that. The registrations can then be processed on the next retry.

The numbers shown are as follows.

Click a number to drill down to see details of the actual records.

In Retry Queue: If an action fails, it joins the Retry Queue and will be tried again.
Maximum automatic retries per action = 3.
Total Retried: The number of retries.
If an action was retried twice, that adds 2 to this number.
Retried Abandoned: The actions that failed three retries.
Validation Errors: No retries possible because failed validation.
For example, a lead could not be created because a mandatory target field had no value in the source field.
See Mappings.
Retry Activity: A chart showing retries by time.
Retry Processing Category: A chart showing retries by category.
Categories include “General”, “System”, “Config”, and “Connection”.
Connection Activity: A chart showing activity per connection over time.

Activity Feed tab

The third tab on the Insights page lists the registrations processed. It notes success or failure, Registration Code, Event, Flow, etc.

This is a rolling history by date.

This is another way to access lower-level data you could access by drilling down in the Summary or Troubleshooting tabs.

The Retry Queue

When an action fails it usually joins the “Retry Queue”. The action then takes its turn to run again.

Failures that cannot be resolved, such as missing mandatory fields, are exceptions. These exceptions do not join the queue.

An action can be retried up to three times. After three retries, the action does not rejoin the queue.

To see the Retry Queue, click Retry in the left navigation panel on the Flows page.

Causes of failure include ones under your control as a planner. Examples include a registration with a status that hasn’t been tagged.

Causes of failure also include technical ones. Examples include a connection being down.

Where you can resolve the cause of a failure, you can do so. Examples include tagging a registration. Examples include setting a flow back to being active.

The action should succeed when retried.

For other failures that do not resolve themselves, you probably need to contact your administrator. You may also need to ask Certain for help.

The interval between retries depends on the severity of the reason. The more serious the reason is, the sooner the retry.

Filtering the Queue

You can filter the records shown in the Retry Queue using these three filters:

Integration: Probably only ‘Webhooks’ unless you have multiple integrations set up.
Status: ‘All Statuses’, ‘Retry’, ‘Error’, ‘Failed’, or ‘Done’.
Category: ‘All Categories’, ‘General’, ‘System’, ‘Config’, ‘Certain API’, ‘Connection’, etc.

Submitting to the Queue

When you click an item in the Retry Queue, you see its full details.

If that knowledge is enough to solve the problem, you can click Submit to Retry Queue. This action adds the item straight to the front of the queue.

Replaying a Flow

If you change an aspect of a flow while the flow has been running for some time, you may want to replay that flow for the same registrations.

Examples of changes include changing its filters.

Replay is not something you can do directly. You can ask Certain to arrange it for you.

Certain may support specifying a date range. Certain may also support specifying an event.

Contents

What is Signal Connector? How does it work?

Prerequisites

Data-Flow Considerations

Credentials in Target Application

Overview of Setup Steps

Setting up Tags

What Are Tags?

Setting Tags Up for an Account

Applying Tags in an Account

Default Registration Statuses

Applying Tags in an Event

Custom Registration Statuses

Custom Registration Properties

Standard Registration Properties (Automatic)

Attendee Types

Events

Registration Questions

Opening Certain Signal Connector

Setting up a Connection

What are Connections?

Adding a Connection

Basic Authentication

Open / No Auth

API Key / Token

OAuth2

Setting Up Flows

What is a “Flow”?

The Flow List

Configuring a Flow

‘Live’ or ‘Test’

Flow Data Source

Available sources

Activate for …

Flow Filters

Event

Profile

Attendee Type Tags

Flow Destination

Setting up a Destination

Mappings

New Mapping setup steps

Metrics Dashboard

Account Insights

Summary tab

Troubleshooting tab

Activity Feed tab

The Retry Queue

Filtering the Queue

Submitting to the Queue

Replaying a Flow