Signal Integration with Webhooks Guide

Certain Signal: Webhooks Integration Guide

This document is a guide to using Certain Signal to integrate with other applications by using Webhooks.

This document does not cover the ‘Advanced Webhooks’ product.

The ‘Advanced Webhooks’ product includes everything described here plus the use of nested JSON.

A separate guide covers integrations using the ‘Advanced Webhooks’ product.

Certain Signal also integrates with Marketo, Eloqua, and Salesforce.

Separate guides cover the Marketo, Eloqua, and Salesforce integrations.

Certain Signal for Webhooks is automatically included with Certain Platform for new customers. Email help@certain.com to add this or any other Signal integration to an instance of Certain. Email help@certain.com with an account name and the Signal integration(s) of interest.

1. What is Signal? 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

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? How does it work?

Certain Signal processes data from events in real-time.

Certain Signal passes the data from Certain Platform to a target third-party application.

The target third-party application can be any app with webhook integration.

Examples of webhook-integrated apps include Slack or Google Forms.

Real-time integration supports sales and marketing teams taking intelligent, prompt action on right event data. Signal processes information at the account level. Signal processes information from events in an account.

Event-level information is based on custom tags attached to data such as Registration Statuses. The guide explains tags in the “Setting up Tags” section.

Important: Signal processes outbound information.

Signal processes outbound information by processing information from Certain.

Signal processes outbound information by sending the information to the target application.

Prerequisites

Data-Flow Considerations

Do events capture data in registration questions that will be synced to the third-party app being integrated?

If events capture data in registration questions, apply tags to those questions.

The guide references Registration Questions.

Do events use different data mappings based on registration status or attendee type? If events use different data mappings, apply tags to those items. The guide references Applying Tags in an Event.

Credentials in Target Application

Signal requires a connection to be set up.

The target third-party application administrator provides information under “Adding a Connection”.

For example, if the chosen Authentication Method is OAuth2, an OAuth2 app must be created in that system. The OAuth2 app creation must provide Endpoint. The OAuth2 app creation must provide Client Id. The OAuth2 app creation must provide Client Secret.

Overview of Setup Steps

| Step | Page |

|---|---|

| On Certain Platform 1. Add tags in the account 2. Apply those tags | Setting Tags Up for an Account Applying Tags in an Account |

| On Certain Signal 3. Add a Connection 4. Configure a Flow | Setting up a Connection Setting Up Flows |

Setting up Tags

What Are Tags?

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

Tags can be applied to generic items in events.

Tags can be applied to custom registration statuses and custom registration properties for use in Certain Signal.

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

For example, events may include several custom registration statuses. In addition to standard registration statuses, events may include custom registration statuses. Tags can be applied to more than one status. Tags can also assign each status its own tag.

When configuring a Flow in Certain Signal, the configuration sends data when an attendee’s Registration Status changes. The configuration specifies the tags applicable to Registration Status changes. The configuration does not specify the statuses themselves. That configuration allows the flow to apply to any event in the 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.

Example object(s include ‘Registration Statuses’ and/or ‘Custom Registration Properties’.

4. Click Add.

5. Repeat as required for the needed number of tags.

6. Important: Add enough tags to apply to all items that will be used in flows (see Setting up Tags).

a. Registration Statuses

b. Custom Registration Properties

7. Add enough tags to apply to all items that will be used in filters for flows (see Flow Filters).

a. Attendee Types

b. Events

Applying Tags in an Account

In each event, apply tags to the relevant information.

Relevant information includes Registration Statuses and Registration Custom Properties.

Attendee Types and Events can be tagged to filter registration records. The guide references Flow Filters.

Default Registration Statuses

Default Registration Statuses 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 standard registration statuses are not used, best practice is to set up tags for all standard registration statuses.

It is essential to tag at least the ‘New’ status.

Certain uses the ‘New’ status “behind the scenes” when first processing each registration.

If standard registration statuses are used, tag them all. Tagged standard registration statuses can then be used in the Flows configured in Signal. The guide references page 9.

Applying Tags in an Event

Custom Registration Statuses

If any flows watch or activate for changes of Registration Status, follow these steps.

The guide references Available sources.

1. In each event, go to Plan > Event Setup > Custom Statuses. 2. Select at least one tag for each status.

Custom Registration Properties

If flows watch or activate for Custom Reg Properties, follow these steps.

The guide references Flow Data Source.

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)

Standard Registration Properties (Automatic) are set up automatically.

Standard Registration Properties (Automatic) use names identical to the properties.

Standard Registration Properties (Automatic) include Complete. Standard Registration Properties (Automatic) include Badge Printed. Standard Registration Properties (Automatic) include On To Do List. Standard Registration Properties (Automatic) include Invoice Generated. Standard Registration Properties (Automatic) include Test.

These tags only appear in Signal. In Signal, flows can be activated for these tags. The guide references Activate for ....

There is nothing to edit on Certain Platform.

Attendee Types

Attendee Types are optional.

Attendee Types are for use with filters.

The guide references Flow Filters.

1. In each event, go to Plan > Event Setup > Attendee Types. 2. Select one or more Tags for each attendee type. 3. Filter registration by attendee type using selected tags. The guide references Filters in Flow Filters.

Events

Events are optional.

Events are for use with filters.

The guide references Flow Filters.

1. In each event that may be included in a filter, go to Plan > Event Setup > Details. 2. Select one or more Tags for the event.

Example filter purpose includes ensuring that only registrations for that event are passed to the target application.

Registration Questions

Registration Questions are optional.

Registration Questions are for use with mapping Certain fields to fields in the target application.

The guide references Mappings.

1. In each event where registration questions capture data from attendees, go to Plan > Event Setup > Questions. 2. Select just one Tag for each question. 3. Selecting more than one tag could result in duplicate data in the target application.

Opening Certain Signal

When Signal is activated for an account, the Account Settings > Implementation menu includes an extra option.

Administrators access the Account Settings > Implementation menu.

The extra option is Signal Real-Time Data Integration. Click Signal Real-Time Data Integration to open Certain Signal in a separate window. Signal runs separately from Certain Platform.

To return from Signal to Certain Platform at any time, click.

Setting up a Connection

What are Connections?

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

Multiple connections can exist. Multiple connections can connect 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.

A connection can be set up before configuring the first flow. A connection can also be set up while configuring a flow. This guide assumes connection setup happens first.

Adding a Connection

As an Administrator, set up one or more Connections for the account.

Set up connections only once.

After setup, use the connections in flows set up for the account.

1. Go to Account Settings > Implementation > Signal Real-Time Data Integration. 2. Certain Signal 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 connection details in the Connection Setup screen that opens.

Connection setup fields and options include:

Target: Use the pre-selected value, Webhook.
Connection Name: Enter a name of choice.

Example: the application name being integrated.

Authentication Type: Select the authentication type.

The authentication choice determines other fields displayed for completion.

Basic Authentication

URL: The endpoint to which Signal must send data.
Content Type: One of the two options.

application/json

x-www-form-urlencoded

Request Method: Select POST or GET, if appropriate.
User Name: A user in the target system must have the necessary minimum permissions, if required.
Password: The user’s password.

Open / No Auth

Open / No Auth is the lowest level of security.

Open / No Auth uses the Basic Authentication fields list.

Open / No Auth is without a User Name or Password.

API Key / Token

API Key / Token: Provided by the administrator of the target application.

OAuth2

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

Grant Type: Select Client Credentials or Authorization Code.
Client Id and Client Secret: These two long strings are unique to the OAuth2 app set up by the administrator.

The guide references Credentials on page 2.

Authorization URL
Access Token URL
Refresh Token URL
Scope: The scope depends on the target app, requirements, and security policies.

Scope might be blank, a keyword, or a URL.

Example: scope can be a URL.

Test Connection URL
Is this a primary connection: Leave this check box clear.

This check box appears for all connections.

The check box 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 correct.

Setting Up Flows

What is a “Flow”?

A flow is a configuration to manage the flow of data from Certain to the target application.

Flows are created from the landing page in Signal.

The guide references Configuring a Flow.

An account can have multiple flows. Multiple flows might all use the same Connection.

A flow needs configuration only once at the account level. When a flow is complete, the flow starts picking up data for each event within about a minute.

Signal runs independently from Certain Platform. Because Signal runs independently, a slight delay happens before changes take effect. The same delay occurs after editing a flow.

The Flow List

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

Certain Signal opens in a separate browser window.

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

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

The Flow List includes an Active column. The Active column shows whether a flow is running. Click the toggle button to change a flow from Active to Inactive or from Inactive to Active.

Configuring a Flow

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

The flow configuration consists of:

Name
Live or Test status
Source: information the Flow looks for, and what information the Flow activates for in events
Filters: optional filters to narrow down information
Destination: where and how information goes into the target application

‘Live’ or ‘Test’

The Live toggle determines whether the Flow is Live or Test.

A Live Flow picks 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 registrations in test events. A Test Flow includes registrations marked as ‘Test’ in live events.

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

Flow Data Source

Next, specify the Source of data for the flow. Applying Flow Filters happens optionally.

The Source of a Flow is what the Flow watches for in Certain. The Source defines when the Flow activates based on that data.

For example, the flow might watch for changes to a Registration Status. The flow might activate if an attendee’s status changes to a status tagged as ‘Registered’.

Available sources

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: Save an incomplete Flow and complete it later.

As soon as a Flow is complete, the flow starts picking up data after the usual minute’s delay.

Activate for …

Choose what the flow should activate for.

Activation uses selecting one or more tags in each relevant object dropdown list.

The guide says that activation can target tags applied to Registration Statuses and/or Registration Properties. Other options may be added depending on what the Flow watches for.

If the Flow watches for Registration Status Change, activate for Registration Statuses.
If the Flow watches for Session Registration Status Change, activate for Session Registration Statuses.
If the Flow watches for Event Create Update, activate for Event Statuses.

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

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

Registration Status tags can be applied to:

standard registration statuses at the account level
custom registration statuses at the event level

Flow Filters

Filter the data going into a flow.

The flow uses three filter types.

The three filter types are:

Event fields
Profile fields
Attendee Type tags

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

Event

Event filter fields include:

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

Profile

Profile filter fields include:

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

Attendee Type Tags

Attendee Type Tags filter fields include:

tags that can be applied to Attendee Types

Note: For custom fields, only enumerated questions are selectable.

Enumerated questions have pre-configured answers.

Enumerated question types include Select, Multi-select, Checkbox, or Radio.

Flow Destination

Select Webhooks from the integrations set up by Certain for the account. Other integrations may also be available to choose from.

Setting up a Destination

1. Give the Destination a Name of choice.

2. Select the Connection to use.

3. Select Webhook as the Action for this connection.

4. Select or add the mappings to use.

Note: A New Connection can be used.

The process for setting up a connection is the same as described in Setting up a Connection.

Mappings

Select or set up a set of mappings.

The destination can use two mappings.

The destination can use a Payload mapping.

The destination can also use an Http Header mapping if required.

The mapping setup process is the same for each mapping.

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

Select a mapping from the drop-down list. If no mappings exist yet, or if existing mappings do not cover needed mapping requirements, click New Mapping.

New Mapping setup steps

1. Give the mapping a name of choice.

Best Practice: For multiple mappings used for different flows, make the mapping names self-explanatory.

Examples include ‘Lead Mapping’ and ‘Contact Mapping’.

2. Obtain a sample JSON from the source.

3. For each target field identified in the JSON, such as FirstName in the example, complete these steps:

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

b. Click the source-field selector to select the source field in Certain that matches that target field.

Example target field is ‘First Name’.

The matching source field in Certain is “FirstName”.

The value of that Certain field populates the “First Name” field in the target application.

4. The available Certain fields used as a source depend on what the flow activates for.

Available source fields can include:

Profile Standard Fields
Profile Custom Fields
Registration Standard Fields
Registration Custom Question Tags
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)

Note: Registration Custom Question Tags includes one field for the question.

Registration Custom Question Tags includes one field for the answer.

The guide references Applying Tags in an Event about not using the same tag for more than one question.

Note: Concatenate multiple source fields for the same target field.

A concatenation can include fixed text.

Example concatenation: for target field ‘Title’, choose source fields ‘Position’ and ‘Organization’. The guide example concatenates ‘Position’ and ‘Organization’. The example concatenation places two spaces and “@” between values.

c. To make a target field a required field, select the checkbox next to it. d. To delete a source field, click the x after its label.

If a required field is missing, the flow triggers a validation error when updating the target application. The flow validation error is normally not fixable. Because validation errors are not normally fixable, the error does not go into the Retry Queue.

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

If no transformation is selected, Signal sends data to the target application unchanged.

The transformation options are:

lower case
Proper Case
UPPER CASE
Trim (removes extra spaces)

More than one transformation can be selected for a field. Example: change to Proper Case and trim.

5. Continue adding target/source field pairs as needed.

If a mapping is selected, two other buttons are enabled with self-explanatory labels:

Edit Mapping
Preview Mapping

6. Save the mapping.

Metrics Dashboard

To see statistics available in Signal, click Metrics in the left navigation panel while looking at flows. Metrics navigation options depend on the flows and their targets.

The first metrics option is Insights. Other links can include Webhook Posts. These other links work the same way as Account Insights.

Account Insights

Select whether the insights display Live Flows or Test Flows.

Select the period for which data is displayed.

Example periods include last 15 minutes, 1 hour, 4 hours, or a number of days.

There are three tabs:

Summary
Troubleshooting
Activity Feed

Summary tab

The Summary tab is the default tab on the Insights page.

Figures on the Summary tab depend on flows and actions. Some figures provide drill-down by clicking the number. Example: clicking Unique Registrations shows registrations processed by any flows in the selected time frame.

You can filter after drilling down. Example filter: filter on an Event Code to see only registrations in that event.

The listed figures apply to the whole account. The figures include all events and registrations. The figures include all flows in the account. Some flows might not be Webhooks integrations. Some figures might not apply to webhooks.

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

Changes Processed: number of registrations processed.

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

The guide notes that the flow processes the created or updated registration in Signal.

Note: Changes Processed can include the same registration more than once.

Example: creating a registration and updating the registration twice totals three “changes”.

Unique Registrations: number of registrations processed.

Counting includes one count per single registration.

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

Actions Triggered: number of actions triggered by flows.

A single flow with a single action can make Actions Triggered equal Changes Processed.

More flows and more actions configured can increase actions triggered.

Actions Not Triggered: displayed only if registrations were processed by flows without actions being triggered.

Example cause is a registration having an untagged status.

Active Flows: number of flows processing registrations during the selected period.

Active Flows is not related to whether flows show “Active” or “Inactive” on the Flow List.

Leads Created: number of leads created in the target application by flows.
Leads Updated: number of leads updated in the target application by flows.
Registration Activity in Certain: overview information.
Processing Status: a pie chart comparing numbers of failures and successes.

Drilling down into failures supports troubleshooting. Example troubleshooting: view why an action failed. If failure cause is addressable, expedite the fix in Signal by going back to Flows. After going back to Flows, click Retry in the left navigation panel. The guide references Retry Queue.

Troubleshooting tab

The Troubleshooting tab is the second tab on the Insights page.

Troubleshooting provides information useful for troubleshooting.

Example: if some registrations are not processed because a Registration Status is not tagged, the Troubleshooting tab supports rectifying the tagging. The next retry can process the registrations.

The Troubleshooting tab provides numbers. Click a number to drill down to details of the actual records.

In Retry Queue: if an action fails, it joins the Retry Queue.

The action retries again.

Maximum automatic retries per action equals 3.

Total Retried: number of retries.

Example: if an action was retried twice, the retry count adds 2.

Retried Abandoned: actions that failed three retries.
Validation Errors: no retries possible because failed validation.

Example validation error: a lead cannot be created because a mandatory target field has no value in the source field.

The guide references ‘Mappings’.

Retry Activity: chart showing retries by time.
Retry Processing Category: chart showing retries by category such as “General”, “System”, “Config”, “Connection”, etc.
Connection Activity: chart showing activity per connection over time.

Activity Feed tab

The Activity Feed tab is the third tab on the Insights page.

The Activity Feed lists registrations processed.

The Activity Feed notes success or failure and includes Registration Code, Event, Flow, etc.

This Activity Feed tab is a rolling history by date. The Activity Feed acts as another way to access lower-level data. The guide describes accessing lower-level data by drilling down in Summary or Troubleshooting tabs.

The Retry Queue

When an action fails, the action usually joins the “Retry Queue”.

In the Retry Queue, the action runs again in turn.

Failures that cannot be resolved do not join the queue. Example failures that cannot be resolved include missing mandatory fields.

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 planner-controlled causes and technical causes. Planner-controlled causes include a registration status that has not been tagged. Technical causes include a connection being down.

Where resolution is possible, resolve the cause. Examples include tagging a registration. An example resolution also includes setting a flow back to being active. After resolution, the action should succeed when retried.

Some failures do not resolve themselves. For non-resolvable failures, contact an administrator or ask Certain for help.

The interval between retries depends on the severity of the reason. More serious reasons retry sooner.

Filtering the Queue

Filter records shown in the Retry Queue using these three filters:

Integration: Probably only ‘Webhooks’.

This depends on multiple integrations being 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 clicking an item in the Retry Queue, view full details.

If full details are sufficient to solve the problem, click Submit to Retry Queue.

The action adds the item straight to the front of the queue.

Replaying a Flow

If a flow changes while the flow has been running for some time, replaying the flow can be needed.

Examples of changes include changing filters.

Replay the flow for the same registrations as before. Replay occurs as if the changes had been made earlier.

Certain cannot do replay directly through the user interface. Certain can arrange replay for the user. Certain might support specifying a date range. Certain might support specifying an event.