The Custom integration lets you connect Triggerbee to an external system using its API, even when there is no native Triggerbee integration available.

You configure how Triggerbee should authenticate with the external system and which API endpoints Triggerbee should use.

With a Custom integration, you can:

Authenticate using OAuth 2.0 (Authorization Code), an API key, or no authentication.
Check whether a visitor belongs to a specific segment.
Send Triggerbee events to your own webhook endpoint.

Before you start - Your API determines the configuration

The configuration depends on the API you are connecting to. There is no configuration that works for every system.

Triggerbee provides the framework for communicating with your API, but the required endpoints, authentication credentials, headers, OAuth configuration, and JSONPaths depend on the system you're connecting to.

When configuring the integration, you'll typically need to know:

Which authentication method the API uses.
The credentials required to access the API.
Which endpoint returns the available segments.
How segments are represented in the API response.
Which endpoint can be used to check segment membership.
How subscribers are represented in that response.
Which endpoint should receive events from Triggerbee.

Refer to the documentation for the API you're connecting to for these details.

If you're unsure about the required configuration, we recommend involving a developer or someone familiar with the external system's API.

How to set up a Custom integration

Step 1 - Configure authentication

In Triggerbee, go to My Triggerbee --> Apps & Integrations and select Custom integration.

The available authentication methods are:

OAuth
API-key
No authentication

Choose the authentication method required by the API you are connecting to.

Option A: OAuth

Choose OAuth for APIs using the OAuth 2.0 Authorization Code flow.

Enter the OAuth configuration provided by the external system.

OAuth client ID
Enter the Client ID for the application you have created in the external system.
OAuth client secret
Enter the Client Secret belonging to the application.
OAuth authorize URL
Enter the endpoint used to authorize access to the external system.
For example:
https://api.example.com/oauth/authorize
OAuth token URL
Enter the endpoint used to exchange the authorization code for an access token.
For example:
https://api.example.com/oauth/token
OAuth scope (optional)
Enter any scopes required by the external API.
For example:
contacts segments

Whether scopes are required, and how they should be formatted, depends on the API you're connecting to.

The Client ID, Client Secret, URLs, and scopes are provided by the system you're connecting to. Refer to its API or OAuth documentation for the correct values.

When the authentication is complete, click Save and move on to step 2 of the configuration.

Full example of oauth setup:

Option B: API-key

Choose API-key if the external API uses a static API key or access token for authentication.

You need to configure two fields:

API-key
Enter the API key exactly as it should be included in requests to the external API.
For example:
Bearer <key>

Some APIs may expect only the key itself, while others require a prefix such as Bearer. Refer to the API documentation for the system you're connecting to.
API-key header (optional)
Enter the HTTP header that should contain the API key.

A common example is:
Authorization

Other APIs may use a custom header such as:
X-API-Key

The required header name is determined by the external API.

For example, if your API expects:
Authorization: Bearer abc123

Configure:
API-key: Bearer abc123
API-key header: Authorization

When the authentication is complete, click Save and move on to step 2 of the configuration.

Option C: No authentication

Choose No authentication if the endpoints you're connecting to don't require authentication. Give your integration a name and add an icon if you'd like.

Only use this option when the external API is intended to accept unauthenticated requests.

Step 2 – Configure segments

The next step determines how Triggerbee retrieves segments from your external system and checks whether a subscriber belongs to a segment.

This configuration is based on the endpoints and response format of the API you're connecting to.

Segments listing URL

Enter the API endpoint Triggerbee should call to retrieve the available segments.

For example:

https://api.example.com/segments

Triggerbee will call this endpoint using the authentication method configured in Step 1.

Segments listing - JSONPath to IDs (optional)

Enter a JSONPath expression that tells Triggerbee where to find each segment's unique ID in the API response.

For example, if the API returns:

[
{"id": "123", "name": "Newsletter subscribers"},   
{"id": "456", "name": "VIP customers"}
]

The JSONPath to the IDs could be:

$[*].id

Segments listing - JSONPath to names (optional)

Enter a JSONPath expression that tells Triggerbee where to find the human-readable name of each segment.

Using the example above:

$[*].name

Triggerbee can then associate each segment ID with the corresponding segment name.

The correct JSONPath depends on the JSON returned by your API. Check the API response and adjust the paths accordingly.

Segments subscriber check URL

Enter the endpoint Triggerbee should use to determine whether a subscriber belongs to a specific segment.

You can use:

{{segmentId}}

as a dynamic value in the URL.

For example:

https://api.example.com/segments/{{segmentId}}/subscribers

When Triggerbee checks a segment, {{segmentId}} is replaced with the ID of that segment.

Subscriber check response path (optional)

If the subscriber endpoint returns a collection of subscribers, use a JSONPath expression to tell Triggerbee how to locate the current subscriber in the response.

You can use:

{{identifier}}

to represent the visitor identifier Triggerbee is looking for.

For example, if subscribers are identified by their email address:

$[?(@.email=='{{identifier}}')]

The exact expression you need depends on the response returned by your API.

Here's a full example of a Segment Setup:

Forward Triggerbee events to your system

Once the integration is in place, you can use Triggerbee Automations to forward Triggerbee events to an external webhook endpoint.

This can, for example, be used to:

Send form submissions to your platform.
Send identified visitor activity to your platform.
Notify your platform when a Triggerbee goal is completed.

The receiving endpoint must be able to accept requests from Triggerbee and use the authentication method configured for the integration, where applicable.

How to configure a webhook event

This can be done either from Campaign Form Settings or from an Automation. Automations can have any trigger, while campaign form settings will trigger the even upon campaign interaction (form submission, click).

In Form Settings or Automations, select Custom Integration --> Send webhook

Example from Automations:

Example from Form Settings:

Then configure the webhook according to:

Webhook URL: The link to your receiving webhook.
HTTP Method: Select your desired method (usually POST for sending new data).

Map any collected data under Field mapping according to someData.yourField. The contents of the event will be sent like this to the webhook:

{
   "someData": {
      "email": "[email protected]",
      "name": "Name"
   }
}

Full example: