This step-by-step guide will walk you through how to set up Splash's HTTP Request integration.

Table of Contents

1. How the integration works
2. What you'll need to get started
3. Configuring the integration
    3.1 Authenticating the integration
    3.2 Defining the request
           3.2.1 Naming the integration
           3.2.2 Identifying the endpoint
    3.3 Providing Headers
    3.4 Selecting which Splash actions will activate the integration
    3.5 Determining which Splash data will be sent
4. Activating and deactivating the integration
5. Editing, duplicating, and deleting the integration
6. Testing the integration
7. Troubleshooting the integration
    7.1 Reading the Activity Log
    7.2 Resolving error messages

1. How the integration works

The HTTP Request integration is designed to send Splash data to third-party systems leveraging REST API endpoints. The system receives the data whenever a set of selected, predefined actions occur in Splash. 

The integration's ability to directly push data to an endpoint makes it versatile for a variety of solutions and systems.

To name a few, the integration can be used to: 

• Print guest badges using a custom badge printing service
• Notify your CRM when a Splash guest unsubscribes from your emails
• Write to a custom scheduling software anytime a Splash event is created
• Alert your mobile event app whenever guests check-in to your event
• Add Splash guests to a Facebook event

We recommended using this integration whenever information needs to be sent to a third-party system that does not already exist as a native integration in Splash.

2. What you'll need to get started

This guide is intended for those who have an understanding of what an HTTP request is and how it works. While being a developer is not required, familiarity with APIs and experience making requests between various services is highly recommended for successful implementation.

To set up the integration, you'll need:

1. A Splash Basic, Professional, or Enterprise team license.

2. Access to the Integrations dashboard on the organization or event-level.

3. API documentation for the external system handy. We'll use this to help customize the integration based on the endpoint's specifications.

3. Configuring the integration

Configuring the integration involves identifying the endpoint, setting triggers, mapping fields from Splash to the third-party system, and determining the circumstances under which the integration launches.

The integration can be configured on either the organizational or event-level.

1. To configure the integration on the organization-level, select the Integrations icon from the left-hand menu of the Events Dashboard. If configuring on the event-level, select the Settings icon in the Event Settings and then open the Integrations tab.

2. Click the New Integration button.

3. Locate the HTTP Request option and select Choose. 

The configuration screen for the integration will automatically open upon selection.

3.1  Authenticating the integration

The integration supports the following Authentication Types:

• No Authentication
  No Authentication should be used if the remote endpoint requires no authentication headers in order to receive data.
  

• Basic
  The Basic Authentication Type requires the username and password of the third-party system to be entered.
  

• Oauth 2.0
  The Oauth 2.0 Authentication Type allows for further customization, but at minimum requires the username and password of the third-party system to be entered.
  

The following authentication information is configurable when selecting Oauth 2.0:

 

Grant Type
The Grant Type only supports password credentials. 

Access Token Request Method
Supported request method types are GET and POST. It's important to remember communication is unidirectional from Splash to an external system, so POST is the most common request method.

Client Authentication
The Client Authentication field supports a Request Body, Request Headers, and the option to Send as Query String.

Content Type
The sections supports application/json, text/plain, and x-www-form-urlencoded Content Types.

Access Token URL
Enter the endpoint in the remote system here to retrieve an Access Token (if required).

Client ID and Client Secret
The unique ID and secret associated with the API client in the remote system is entered here. 

Scope 
The scope of the request being made to the remote system (e.g. write:user, read:org, etc.) is entered here. Multiple values can be added within the Scope field by using spaces to separate each entry.

Add Authorization Data To
Authorization can be sent as a request header.

3.2 Defining the request

After authentication is completed, navigate to the Request Settings tab to configure the integration. 

3.2.1 Naming the integration

Enter a name for the configuration in the Integration Name field. By default, the field displays HTTP Request as the title of the integration.

If you're planning to create multiple HTTP Request configurations, we recommend entering a unique and descriptive integration name in this field (eg. Ping Twilio on RSVP, Send Unsubscribe to MailChimp, etc).

Otherwise, feel free to skip this section and leave the name of the integration as is.

3.2.2 Identifying the endpoint

Configuration begins by defining the request method, identifying the endpoint's URL, and selecting the type of content being transmitted.

The integration supports the following request methods:

GET
POST
PUT
PATCH
DELETE

To complete this section:

1. Select a REST Method from the drop-down list in the Method field.

2. In the next field, enter the URL of the external system's endpoint.

3. In the Content Type dropdown, choose how the field mappings should be sent with the request. The data can be encoded as a part of the URL or sent as JSON in the request body. Splash will automatically append the corresponding Content Type header to the request.

3.3 Providing Headers

Completing this section is optional, depending on the remote system’s requirements. Information on whether Headers are supported or required can be found in the system’s API documentation.

The Headers section consist of Key-Value pairs, which can be added by clicking on the addition icon below the provided field. To remove a Key-Value pair, click on the minus icon to the right of each Key-Value field. 

An example of Key-Value formatting is provided below:

Key: Content-Language
Value: de-DE

In this example, the Key-Value pair would tell the receiving server (which supported the content language Header) that the content was German. Formatting for any supported or required Headers can be found within the systems’s API documentation. We told you that you'd want to keep this documentation handy! 

3.4 Selecting which Splash actions will activate the integration

Once the endpoint and any necessary headers have been identified, the next task is to set up the Triggers and Trigger Conditions.

Triggers define the Splash actions that will activate the integration, while the Trigger Conditions specify when the Triggers will launch.

Triggers

You'll starting by defining the Triggers for the integration.

1. In the Trigger field, select a Splash feature to initiate the integration from the drop-down list. Only one Trigger can be selected per configuration. 

2. In the Actions field that appears, select any actions that should activate the integration. The available options are determined by the Splash feature selected in the Trigger field.

While only one Trigger can be selected per configuration, the Action field is a multi-select list that allows for several actions to initiate the integration. When selecting from the Actions field, it's important to remember that API endpoints have varying rate limits and different tolerance levels for high activity.

The rate limits associated with the endpoint should be taken into consideration with the frequency in which the Splash action will occur. For example, a guest RSVPing will happen more frequently than an event being created. We recommending checking the external system's API documentation or contacting the system's administrator to confirm the endpoint's rate limits.

Trigger Conditions 

Once your triggers have been set, navigate to the Trigger Conditions section. 

Trigger Conditions limit the integration to initiate based on certain specifications. If your team's workflow requires it, you can limit the integration to only launch for specific Event Types and/or for specific Groups.

By leaving these options blank, the integration is set to apply to all Event Types and Groups. By selecting both, the integration is limited by both Event Types and User Groups.

• Only trigger for specific event types
  Select this checkbox to allow specific Event Types to initiate the integration. The multi-select list is enabled once the box is selected. This list is based on Event Types in your organization.
  
  

• Only trigger for specific groups
  Select this checkbox to set the integration to initiate for specified User Groups. The multi-select list is enabled once the box is selected. This list is based on User Groups in your organization.

3.5 Determining which Splash data will be sent

This section is used to define how information is sent to the receiving system from Splash.

Fields are mapped by choosing the data for Splash to send. This consists of a Splash Object and an associated Splash Field. Next, the Remote Field in the external system is identified for where the information is sent.

The Ignore empty values checkbox at the top of the Field Mappings section is used to specify whether empty values will be ignored. When this checkbox is selected, if a value isn't provided, the integration treats it as though the mapping doesn't exist.

To complete this section:

1. Click the Add a Field button under the Field Mappings section.

2. In the Splash Object field, select the object to map.

3. In the Splash Field, select the data field to map.

4. In the Remote Field, enter the name of the field in the remote system that the Splash information is being sent to. Make sure that the Remote Field name is identical to the field name in the receiving system. Any errors may result in data not transferring. 

5. Repeat these steps to map all of the desired values.

6. Once all mappings are complete, click the Save button.

In the event a field needs to be removed, click the trash icon to the right of the mapping to delete it.

We don't recommended using the HTTP Request integration to makes calls back to the Splash API. This can create a looping effect and increased API calls.

4. Activating and deactivating the integration

Activating the integration is the final step in the configuration process. By default, the integration will be deactivated upon creation. 

Scroll to the top of the integration section and click the On/Off toggle On to activate it.

To deactivate the integration, click the On/Off toggle again. The toggle turning green indicates that the integration is activated while grey indicates that the integration is deactivated.

5. Editing, duplicating, and deleting the integration

The integration is built with customization in mind, meaning that it can be edited, duplicated, or deleted at any time.

Editing

Any edits made to the integration will not be retroactively applied to any attendees or events. The changes will only be applied after the edits are saved.

Settings to duplicate and delete the integration are housed within the menu button (the three vertical dots) at the top of the integration screen. 

Duplicating

Recreating integrations with complex Field Mappings or Trigger Conditions can be accomplished through duplication. Duplicating the integration will copy all saved integration settings (aside from the Authentication Type) and will appear at the bottom of the Integrations Dashboard.

Deleting

Deleting the integration will only delete that specific instance of the integration. It will not delete any duplicated instances of the integration.

6. Testing the integration

To ensure everything is working correctly, the integration should be tested. To do so, create a test event and perform an action that you selected from the Action fields in section 3.4 of the guide.

For this example, we'll submit an RSVP to a new event. 

1. Head to the Events Dashboard.

2. Click New Event.

3. Enter test event information and click Next Choose Theme.

4. Select an appropriate theme for the event and design the page as desired.

5. Simulate an RSVP by clicking the View as Guest from the Event Dashboard.

6. Click RSVP and fill out the response form using your email.

7. Click Submit.

8. Check to see if the integration worked properly when the RSVP was submitted by accessing the Activity Log. A 200 code should appear confirming a successful sync.

9. Check the third-party system to confirm that the selected Splash information was sent.

7. Troubleshooting the integration

The Activity Log serves as the primary resource for troubleshooting integration issues. It logs all successfully synced data along with any error messages.  

7.1 Reading the Activity Log

To view the Activity Log:

1. Open the Integrations dashboard.

2. Open the HTTP Request configuration and scroll to the bottom.

3. Click the Activity Log button.

The All Logs section within the dialog window displays a list of all the activity in the integration. Click Show Detail to view more details about that activity. A 200 code will display for all successfully synced data, while any sync failures will result in varying error codes.

7.2 Resolving error messages

The Errors Only section of the Activity Log will display JSON representation of the request sent and the response from the remote server. The code displayed for the error will be dependent upon the integrated system, as not all services may abide by the different HTTP status codes.

The codes typically read as follows:

404
This code means the endpoint is not found. This can be due to the endpoint being typed incorrectly or the wrong HTTP method being selected. 

400
This code signifies a bad request and typically means that the entered Content Type (application/json versus www-url-formencoded) is incorrect or that a Field Mapping is improperly formatted or missing.

500
This code appears when the remote server throws an error. The integrated system’s administrator will need to be directly contacted for more information whenever this error appears. 

Since the error code populated in the Activity Log is a response from the integrated system, we recommend copying the error information and sending it directly to the external system’s administrator for further clarification about the issue with the request.