Certain Signal Connector: Webhooks Integration Guide

1 month ago Updated

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. Please see the separate guide to integrations using that product.

Certain 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. If you are interested in adding this or any other Signal Connector integration to your instance of Certain, please email features@certain.com, including your account name and the Signal Connector integration(s) you are interested in.

Contents

What is Signal Connector? How does it work?

Certain Signal Connector processes data from your events in real time.

Certain Signal Connector passes data from Certain Platform to your target third-party application.

Your target third-party application can be any app with webhook integration, such as 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. For event-level information, Signal Connector uses the custom tags you attach to data such as Registration Statuses. This guide explains the custom tags.

Important: Signal Connector processes outbound information.

Signal Connector processes information from Certain and sends it to your target application.

Prerequisites

Data-Flow Considerations

Credentials in Target Application

For you to set up a Connection in Signal Connector (see page 5), the administrator of your target third-party application will need to provide you with the information described under "Adding a Connection" on page 6.

For example, if your chosen Authentication Method there is OAuth2, then your target application administrator will need to create an OAuth2 app. Your target application administrator will then provide Endpoint, Client Id, and Client Secret.

Overview of Setup Steps

On Certain Platform

| Step | See Page |

|---|---|

| 1. Add tags in the account | 3 |

| 2. Apply those tags | 3 & 4 |

In Certain Signal Connector

| Step | See Page |

|---|---|

| 3. Add a Connection | 6 |

| 4. Configure a Flow | 8 |

Setting up Tags

What Are Tags?

Tags are a way of identifying event-level data using labels you set at the account level.

You can then apply those tags to generic items in events. These generic items include custom registration statuses and custom registration properties for use in Certain Signal Connector. Tags can be used for other purposes as well, but this guide does not cover that.

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 (see page 10):

7. Also add enough tags to apply to all of the following that you will use in filters for flows (see page 10):

Applying Tags in an Account

In each event from which you want information to flow through Certain Signal Connector, apply tags to the relevant information.

Apply tags to Registration Statuses and Registration Custom Properties.

You can also tag Attendee Types and Events. Those tags let you filter registration records by attendee type or event. See Filters on page 10.

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 do not use any standard registration statuses, best practice is to set up tags for all of them.

Tag at least the New status.

Certain uses the New status behind the scenes when first processing each registration.

If you do use standard reg statuses, tag them all. You will need tagged reg statuses to use them in the Flows you configure in Signal Connector: see page 8.

Applying Tags in an Event

Custom Registration Statuses

If any of the Flows you configure in Signal Connector will watch or activate for Custom Reg Statuses (see page 9), follow these steps:

1. 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 (see page 9), follow these steps:

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.

These tags have names identical to the properties themselves: Complete, Badge Printed, On To Do List, Invoice Generated, and Test.

You only see these tags in Signal Connector. Signal Connector lets you activate Flows for them (see page 9). There is nothing to edit on Certain Platform.

Attendee Types

(Optional — for use with filters — see page 10.)

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 page 10.

Events

(Optional — for use with filters — see page 10.)

1. In each event 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 page 11.)

1. In each event in which you use registration questions to capture data from attendees, and wish to pass those answers 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 — available to Administrators — includes an extra option:

Click the Signal Connector Real-Time Data Integration link to open Certain Signal Connector in a separate window. Certain Signal Connector runs separately from Certain Platform.

Note: To return from Signal Connector to Certain Platform at any time, click the exit icon.

Setting up a Connection

What are Connections?

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

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

Each Flow (see page 7) 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 only do this once.

You can then use Connections in the Flows you set up (see page 7, below).

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.

This could be just the name of the application with which you are integrating, for example.

Your choice determines the other fields displayed for you to complete.

| Basic Authentication | Open / No Auth | API Key / Token | OAuth2 | |---|---|---|---| | URL | URL | API Key / Token | Grant Type | | Content Type | Content Type | | Client ID | | Request Method | Request Method | | Client Secret | | User Name | | | Authorization URL | | Password | | | Access Token URL | | | | | Refresh Token URL | | | | | Scope | | | | | Test Connection URL |

Basic Authentication

Open / No Auth

The lowest level of security.

API Key / Token

OAuth2

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

It is displayed for all connections.

It is only relevant to Eloqua, Marketo and Salesforce integrations requiring backwards compatibility.

1. Click Save & Test. 2. If the test is successful, click Close. 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 is a configuration to manage 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. These flows might all use the same Connection (explained above).

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 delay occurs because Signal Connector runs independently from Certain Platform. If you edit a flow, 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:

See immediately below.

See page 9.

See page 10.

See page 10.

"Live" or "Test"

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

A Live Flow will pick up all live registrations in live events. A Live Flow ignores test registrations, even in live events.

A Test Flow picks up all test registrations. A Test Flow includes all registrations in test events. A Test Flow also includes any registrations marked as "Test" in live events.

Best Practice: Set a new flow up as Test.

Test the flow before setting it to Live.

Flow Data Source

Next, specify the Source of data for the flow.

You can optionally apply Filters.

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

For example, the flow might watch for any change to a Registration Status. The flow might activate 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:

Note: You can always save an incomplete Flow and complete it at a later date.

As soon as a Flow is complete, 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.

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:

The tags available for selection are those set up for that object. See page 3.

For example, the tags for Registration Statuses include Registration Status tags.

You can apply these tags to:

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, and Attendee Type tags.

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

Note: For custom fields you can only select "enumerated" questions.

Enumerated questions are questions that have pre-configured answers.

Examples of enumerated question types include 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 page 5.

3. Select Webhook as the Action for this connection.

4. Select or add the mappings to use, as described next.

Mappings

Select or set up a set of mappings.

You can have two mappings.

One mapping is for the Payload.

A second mapping is 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:

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 "Form 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:

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.

The Certain fields you can choose from as the source of the data going into each target field in your target application will include some of the following, depending on what your flow will activate for. If the flow will activate for Event Statuses, then you can only map event fields.

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", separated by two spaces and "@":

Title = Position + " @" + Organization

To make a target field a required field, select the checkbox next to it. If a required field is missing, there will be a validation error when the flow tries to update your target application. This is not normally fixable. This does not go into The Retry Queue.

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 means the data will be sent to your target application unchanged.

The options are:

Note: 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.

If you selected a mapping then two other buttons are enabled, with self-explanatory labels: Edit Mapping and Preview Mapping.

6. 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 for Metrics depend on the flows and their targets. The first choice will be Insights. Other links may include, for example, Webhook Posts. These 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 when you have drilled 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. These figures cover all events and registrations. These figures also cover all flows in your account. Your account might include flows that are not Webhooks integrations. Some figures shown may not be applicable to webhooks.

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

Changes Processed increments each time a registration is created or updated in Certain.

The changes are then processed by a flow in Signal Connector.

Note: This will often include the same registration more than once.

For example, creating a registration and then updating it twice would total three "changes".

Unique Registrations counts any single registration only once.

Unique Registrations may be the most relevant figure on the page.

Unique Registrations is likely to be lower than Changes Processed.

For example, if Joe Citizen's registration was processed three times, then Changes Processed increases by 3.

Those changes all apply to the same registration.

Unique Registrations increases by only 1.

If you only have one flow with one action, then Actions Triggered could match Changes Processed.

The more flows you have and the more actions configured in those flows, the more actions may be triggered.

This could be caused, for example, by a registration having an untagged status.

This Active Flows value is not related to whether the flow is shown as "Active" or "Inactive" on the Flow List.

Drilling down into the failures provides a high-level view for troubleshooting.

The failures view can show why an action has failed.

If you can address the failure, you can expedite the fix in Signal Connector.

Expediting occurs by going back to Flows and clicking Retry in the left navigation panel.

See Retry Queue on page 17.

Troubleshooting tab

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

If some registrations are not processed because a Registration Status is not tagged, the Troubleshooting tab gives you the chance to rectify tagging. Rectifying tagging allows the registrations to be processed on the next retry.

The numbers shown as follows provide drill-down access to details of the actual records.

See page 17.

The action is retried again.

Maximum automatic retries per action = 3.

If an action was retried twice, Total Retried increases by 2.

For example, a lead could not be created because a mandatory target field had no value in the source field.

See "Mappings" on page 11.

Categories include "General", "System", "Config", "Connection", etc.

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. It is another way to access lower-level data you could see by drilling down in the Summary or Troubleshooting tabs.

The Retry Queue

When an action fails, it usually joins the "Retry Queue".

The Retry Queue reruns the action after the failure.

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. One example is a registration with a status that has not been tagged. Causes of failure also include technical ones. One example is a connection being down.

Where you can resolve the cause of a failure, you can fix the issue. One example is tagging a registration. Another example is setting a flow back to being active. You can do this as needed. The action should succeed when retried.

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

The interval between retries depends on the severity of the reason. More severe reasons trigger sooner retries.

Filtering the Queue

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

Submitting to the Queue

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

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

Replaying a Flow

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

You replay the flow for the same registrations as before.

This happens as if the changes had been made earlier.

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

You may be able to specify a date range. You may also be able to specify an event.

Source:

Published:

Keywords: Certain Signal Connector, Webhooks, Certain Platform