A custom integration can connect Journeys to a third-party system that isn’t in the app marketplace.
Each integration is created and maintained in its own Integration Builder, where you set up authentication, add endpoints, and test them.
Before you start
You need:
The system's API documentation. This is where you find the base URL, the available endpoints, and the fields each endpoint expects.
Credentials for the system. Usually an API key or token, depending on the system.
The Admin or Editor role in your Journeys company account.
Setting up a custom integration is technical work. If you aren't comfortable reading API documentation, get IT involved.
Step 1: Create the custom integration
Click Add new integration in the top-right corner
Fill in the details:
Name (required)
Description (optional)
Integration logo (optional, .png, .jpg or .svg)
Base URL of the third-party system, from its API documentation
Click Add custom integration
The integration is created and its Integration Builder opens automatically.
Step 2: Set up authentication
Authentication is how Journeys proves to the other system that it's allowed to send requests. Each integration has one authentication method, and it applies to every endpoint in that integration.
On the Details tab, click Authenticate
Choose the authentication type the system uses. Read its API documentation to learn which one is correct
Fill in the appropriate credentials and save
Some types must be tested successfully before they can be saved. If the test fails, check the credentials and the base URL.
Once authentication is set, the Authenticate button becomes Edit. Click it if you need to change authentication later.
Step 3: Add endpoints and test them
Journeys exchanges data with other systems via endpoints.
An endpoint is a reusable request that performs a single action in another system.
Examples include:
Create an employee in BambooHR
Look up an employee by email
Send a message to a Slack channel
Mark an issue as done in Jira
Add an endpoint
Click Add Endpoint in the top-right corner
Choose whether to add:
API endpoint for outgoing requests
Webhook for receiving incoming data from the other system. See Webhooks.
Fill in the endpoint's URL, method, and a JSON example payload that contains the fields you want to include, then click Save.
Configure request values
Journeys adds a request value for every field in the request body and every {{placeholder}} in the URL. These are the fields people fill in when they use the action in a journey, so it's worth setting them up properly.
For each request value you can:
Change the type, for example single line text, long text, number, file or select
Change the label, which is the name people see in the journey action
Set a default value
Hide the field from the action sidebar in journeys
Make the field required
Response values
Journeys adds response values automatically each time you test the endpoint. Response values are essentially the data you received from the system. You can change the types and labels just like for request values.
You can also add custom response values, which are computed with jq queries. See jq queries to learn how to write them.
Test your endpoint
Before an endpoint can be used as an action in journeys, it must be successfully tested in the Integration Builder.
An endpoint will not appear in the Journey Builder until a test request has returned a successful response. This ensures only working endpoints can be used in journeys.
Step 4: Use the custom integration in a journey
Once an endpoint has been created and successfully tested:
It appears in the list of available custom integration actions in all journeys.
It can be added as an action in any journey.
Click to action to see the request values it needs. Here you can dynamically map data from previous actions
Response values returned by the action can likewise be used as input in later actions
