1. Pendo Help Center
  2. Integrations
  3. Twilio Segment integration

Send server-side Track Events from Twilio Segment to Pendo

Last updated:

You can send Twilio Segment data to Pendo by setting up a destination in Twilio Segment (herein, Segment). Pendo has two destinations in Segment: the Pendo Web (Actions) destination and the Webhooks (Actions) destination. The Pendo Web (Actions) destination is the standard destination for sending data to Segment and is how you can install Pendo through Segment.

This article describes how to set up the Webhooks (Actions) destination, which can be configured instead of or in addition to the Pendo Web (Actions) destination. You might set up both destinations because the Pendo Web (Actions) destination only supports client-side data from web applications, and you either:

  • Want to receive data from your mobile application, which can only be server-side data.
  • Want to receive server-side and client-side Track events from your web application, in addition to visitor and account metadata.

Setup overview

There are two Pendo destinations in Segment that use the Destination Actions framework. This framework allows you to control how Segment sends event data to your Pendo Web (Actions) destination. You can set up one or both destinations in Pendo.

If you want to receive server-side Track events in addition to client-side data for your web application, you must set up the Pendo Web (Actions) destination and then additionally:

  • Create, configure, and turn on a Webhooks (Actions) destination in Segment. This is a different destination to the standard Pendo Web (Actions) destination in Pendo.
  • Ensure that Send Track Events is turned off in the Pendo Web (Actions) destination. This is to avoid duplication caused by having two destinations.
  • Configure client-side Track Events to send groupId to properties in the body of the request. This is because turning off Send Track Event disrupts the otherwise automatic process of adding groupId to a client-side Track Event.

You can also just set up either one or the other destination, depending on your needs: 

  • Set up the Pendo Web (Actions) destination for client-side data from web applications, including visitor metadata, account metadata, and client-side Track Events. For information about this destination, see Send Twilio Segment data to Pendo.
  • Set up the Webhooks (Actions) destination for server-side Track Events. This can be from web and mobile applications. If you’ve integrated Segment with a web application, this destination also sends client-side events.

If you’re setting up both destinations, follow all the instructions in this article. 

If you’re only setting up the Webhooks (Actions) destination, then you don’t need to follow the instructions outlined in the Avoid data duplication section in this article. You do, however, need to follow all the instructions outlined in Prepare your Track Events, which includes instructions for both client-side and server-side Track Events. 

If you’re only setting up the Webhooks (Actions) destination for a mobile application rather then a web application, then you only need to follow the instructions under Configure server-side Track Events to send through Webhooks (Actions).

The Webhooks (Actions) destination in Segment

The Webhooks (Actions) destination is different from the Pendo Web (Actions) destination in Segment. The Pendo Web (Actions) destination only supports client-side data from web applications. You can set up the Webhooks (Actions) destination to send server-side data, often referred to as Cloud-mode in Segment. This allows you to send data to an external URL whenever specified server-side events occur.

The Webhooks (Actions) destination sends server-side Track Events through one of the following endpoints:

  • For the default US environment: https://data.pendo.io/data/segmentio/YOUR PENDO_API_KEY
  • For the US1 environment: https://us1.data.pendo.io/data/segmentio/YOUR PENDO_API_KEY
  • For the EU environment: https://data.eu.pendo.io/data/segmentio/YOUR PENDO_API_KEY
  • For the Japan environment: https://data.jpnpendo.io/data/segmentio/YOUR PENDO_API_KEY

Your Pendo API key is a 32-digit string that maps the data that Pendo collects to the application in your Pendo subscription. Find your Pendo API key in the App Details tab of your application settings.

Step 1. Create a Webhooks (Actions) destination

  1. Go to Workspace > Destinations > My destinations.
  2. Select + Add destination. This opens the Catalog.
  3. Search for and select Webhooks (Actions).
  4. Select Add destination in the top-right of the page. This opens the Select data source page.
  5. Choose the JavaScript data source to connect the destination to. This could be any of your applications that send the server-side Track Events that you want to pass to Pendo. 
  6. Select Next. This opens the Setup page.
  7. Add a Destination name.
  8. Choose Fill in settings manually from the dropdown menu.
  9. Select Create destination in the bottom-right corner of the screen. This takes you to your newly created destination in Segment.

Step 2. Configure your Webhooks (Actions) destination

  1. In your new destination, open the Mappings tab at the top of the page.
  2. Select + New Mapping.
  3. Search for and select the Send action. This opens the Send form.
  4. Under Select events to map and send, choose Event Type plus is plus Track. This defines the trigger that sends your a matching event to the destination.</code">
  5. Under Add test event, select Load Test Event from Source. This allows you to preview the fields that you can map to your destination.
  6. Under Select mappings, define the mappings of event fields in your data source to your destination:
    • In the first field under data source, enter one of the URLs. The URL you enter depends on the data environment that you host Pendo in. Replace YOUR_PENDO_API_KEY at the end of the URL with your actual application key, which you can find in your application settings.
    • In the second field under your data source, choose POST as the Method under Webhooks (Actions).
    • In the next field under your data source, choose 0 (zero) as the Batch size under Webhooks (Actions).
    • Leave Headers blank.
    • Choose Select Object and then, under Event Variables, search for and select The entire event. This adds $event to the dropdown menu.
    • Choose No in the final field under your data source as the answer to Enable Batching?
  7. Under Send test event, select Send test event to destination. This sends the event using the new mappings so that you can verify these mappings in Webhooks (Actions). A message that says 200 OK indicates that the destination successfully handled the test event. 
  8. Select Save. This opens your destination page.
  9. In the Mappings tab, enable the mapping using the toggle under the Status column. This prompts Segment to start sending events that match the trigger condition from your application’s data source to the Webhooks (Actions) destination.

Step 3. Turn on your Webhooks (Actions) destination

  1. In your Webhooks (Actions) destination, open the Settings tab at the top of the page.
  2. Use the toggle under Enable Destination to prompt Segment to start sending data based on the configuration in the Mappings tab for Step 2.
  3. Select Save Changes at the bottom of the page.

Avoid data duplication

If you’ve configured and enabled both Webhooks (Actions) and Pendo Web (Actions) using the same JavaScript data source so that you can send both client-side and server-side data to Pendo, you must also turn off Send Track Event in Pendo Web (Actions). This is to avoid sending the same client-side Track Events twice.

  1. Go to Workspace > Destinations > My destinations.
  2. Open your Pendo Web (Actions) destination. 
  3. Open the Mappings tab.
  4. Turn off the mapping for Send Track Event using the toggle under the Status column.

You must now also edit your client-side Track Events to pass groupId as a property. This is because the Pendo Web (Actions) destination is no longer sending client-side Track Events, and so groupId is no longer included automatically. You therefore need to pass the groupId within the analytics.track() call. For more information and instructions, see Configure client-side Track Events to send through Webhooks (Actions) in this article.

Prepare your Track Events

If you’ve configured and enabled Webhooks (Actions) for a web application, you must also prepare your Track Events to send both client-side and server-side data through Webhooks (Actions) before sending data to Pendo from Segment. For a mobile application, you must prepare your server-side Track Events only.

Preparing your Track Events involves ensuring that the data flows to Pendo in the supported format. You can investigate how Segment sends events before they reach the destination using Segment’s source debugger in Connections > Sources > Debugger, which shows you payload information.

  • A client-side Track Event is sent through a track call, and so this appears as analytics.track() in Segment’s source debugger. 
  • A server-side Track Event is sent through the API, and so this appears as a URL in Segment’s source debugger. 

Configure client-side Track Events sent through Webhooks (Actions)

You must configure client-side Track Events if you have turned off Send Track Event in your Pendo Web (Actions) destination to avoid duplication of data. This stops us from being able to automatically associate Account ID with groupId. You must therefore actively include groupId within properties in the body of the request for client-side Track Events. This sends Track Event properties to Segment’s properties object. Passing data in Segment’s context object doesn’t associate the data in Pendo.

Update the analytics.track() call in your application code to pass groupId in the properties object to associate an event with an account. For example:

analytics.track('Track Event Name', {
    exampleKeyName: "exampleValue",
    groupId: "segmentaccountid"
  })

Configure server-side Track Events sent through Webhooks (Actions)

You must configure server-side Track Events to send through Webhooks (Actions) regardless of whether you’re using the Webhooks (Actions) destination by itself or with the Pendo Web (Actions) destination, and regardless of whether this is for a mobile or a web application.

  • For Visitor ID, update your server-side track call to pass userId in the event payload at the top level. This becomes the Visitor ID in Pendo. 
  • For Account ID, you can pass groupId in one of two places: at the top level or nested within the properties object. The groupId becomes the Account ID in Pendo. 

The following code block is an example of a track call that associates a Visitor ID and Account ID to the event in Pendo at the top level:

curl --location 'https://api.segment.io/v1/track' \
--header 'Content-Type: application/json' \
--data-raw '{
      "event": "Example Event Name",
      "userId": "123",
      "groupId": "account",
      "properties": {
          "exampleKeyName": "exampleValue"
      },
      "writeKey": “<YOUR-WRITE-KEY>”
  }'

The following code block is an example of a track call that associates an Account ID to the event in Pendo nested in the properties object:

curl --location 'https://api.segment.io/v1/track' \
--header 'Content-Type: application/json' \
--data-raw '{
      "event": "Example Event Name",
      "userId": "123",
      "properties": {
          "groupId": "account",
          "exampleKeyName": "exampleValue"
      },
      "writeKey": “<YOUR-WRITE-KEY>”
  }'
Was this article helpful?
1 out of 1 found this helpful

Articles in this section