Destination Functions

NOTE: Functions are currently in Public Preview. If you are interested in joining the Public Preview, navigate to the Build page in your catalog here. The use is governed by (1) Segment First Access and Beta Terms and Conditions and (2) Segment Acceptable Use Policy.

Destination Functions allow you to transform and annotate your Segment events and send them to any external tool or API with a few lines of JavaScript. You can even send Segment events to your internal APIs for further handling.

Here are some examples of Destination Functions are being used by early adopters:

  • Microsoft Teams : trigger notifications/messages on a Teams workspace on important events like Signed Up or Order Placed.
  • ChargeBee : sync subscription information by sending events like Subscription Started, Subscription Updated, Subscription Removed etc.
  • Typeform Surveys : trigger a user dissatisfaction survey on Typeform when a user uninstalls your app, for example when an App Uninstalled event is fired.

The illustration below explains how you might use a Destination Function:

When a page call is sent to Segment, Destination Functions transform the Segment event payload to match the destination’s spec. The transformed Event is sent to the destination tool.

Getting started

Creating your Destination Function

To create a Destination Function:

  1. In your Segment Workspace, go to the Catalog, and click the Functions tab.
  2. Click New Function.
  3. Select Destination Function and click Build.

Writing your function

When you click Build button, a code editor opens so you can configure your destination logic. Segment provides templates that make it simple to send data to a JSON API or other common use cases.

Start by replacing the generic endpoint provided with the API endpoint (URL) for your tool or internal service.

Functions Editor

For each event sent to your Destination Function, Segment invokes your function based on the event type. (Unless prevented by Destination Filters).

You can define and export functions for each type in the Segment Spec that you want to handle:

  • onIdentify
  • onTrack
  • onPage
  • onScreen
  • onGroup
  • onAlias
  • onDelete

Two arguments are provided to the function: the event payload and the settings. All Destination Functions have an apiKey setting by default.

  • The Event argument to the function is the Segment Event Data payload.

    Note Only Event Sources are supported at this time. Object Source data is not supported.

  • The Settings argument to the function contains user settings like apiKey and any custom settings and secrets that you add (coming soon!).

The Functions are “async/await” style JavaScript, and use the Fetch API in the pre-loaded fetch package for external requests. This ensures seamless integration with the Event Delivery tab in the Segment dashboard for your Destination.

Here’s a basic example of a function that POSTs the event to a “request bin” for introspection. You can go to RequestBin to create your own endpoint to experiment with.

The JavaScript below builds a query string for the URL, sets a basic authentication header, and sends a JSON body:

const endpoint = ""

async function onTrack(event, settings) {
  const url = new URL(endpoint);
  url.searchParams.set("ts", event.timestamp);

  const res = await fetch(url.toString(), {
    body: JSON.stringify(event),
    headers: new Headers({
      "Authentication": 'Basic ' + btoa(`${settings.apiKey}:`),
      "Content-Type": "application/json",
    method: "post",

  return await res.json() // or res.text() to avoid parsing response as JSON

The function returns data to indicate a success. In the example above we simply return the request body.

You can also throw an error to indicate a failure. In the above example, try changing the endpoint to https://foo and you’ll see it throws a FetchError with the message request to https://foo/ failed, reason: getaddrinfo ENOTFOUND foo foo:443

There are three pre-defined error types that you can throw to indicate that the function ran as expected, but data could not be delivered:

  • EventNotSupported
  • InvalidEventPayload
  • ValidationError

Here are basic examples using these error types:

async function onGroup(event, settings) {
  if (! {
    throw new InvalidEventPayload("Company is required")

async function onPage(event, settings) {
  if (!settings.accountId) {
    throw new ValidationError("Account ID is required")

async function onAlias(event, settings) {
  throw new EventNotSupported("alias is not supported")

If you do not supply a function for an event type, Segment throws an implicit EventNotSupported error.

You can read more about error handling below.

Runtime and dependencies

Destinations Functions are run using Node.js 10.x. The following dependencies are pre-installed in the function environment:


A modern JavaScript utility library delivering modularity, performance & extras. See the lodash docs.


The official Amazon Web Services SDK. See the AWS docs.


The crypto module provides cryptographic functionality that includes a set of wrappers for OpenSSL’s hash, HMAC, cipher, decipher, sign, and verify Functions. See Crypto docs.

Fetch API

The Fetch API provides a JavaScript interface for accessing and manipulating parts of the HTTP pipeline, such as requests and responses. It also provides a global fetch() method that provides an easy, logical way to fetch resources asynchronously across the network. See the Fetch API docs.


The fetch() method starts the process of fetching a resource from the network, returning a promise which is fulfilled once the response is available. See docs.


The Request interface of the Fetch API represents a resource request.


The Response interface of the Fetch API represents the response to a request.


The Headers interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing. A Headers object has an associated header list, which is initially empty and consists of zero or more name and value pairs.


The URL interface is used to parse, construct, normalize, and encode URLs. It works by providing properties which allow you to easily read and modify the components of a URL.


The URLSearchParams interface defines utility methods to work with the query string of a URL.


The atob() function decodes a string of data which has been encoded using base-64 encoding.


The btoa() method creates a base-64 encoded ASCII string from a binary string.

️Settings and secrets

Settings allow you to pass different variables to your function so that you can use it across multiple sources which might have different configurations.

For example, if we include an settingKey settings string, you can access this from your code using dot notation on the settings object as follows:

async function onRequest(request, settings) {
  let settingValue = settings.settingKey;

You can include multiple setting types including strings, booleans, string arrays and string objects to support your use case. You can also mark a particular setting as being required and/or sensitive (encrypted), if needed.

Common use cases for using multiple settings include:

  • Configuration and dynamic mappings for user-configurable flow control in your Destination Function. Create a Destination Function once and allow your users to configure instances of that function multiple times with custom settings.
  • Additional secrets. This is for use cases like client credentials authentication models, or for when calling multiple external APIs, for example in enrichment workflows or when looking up stored user traits and identifiers by any externalId from Segment’s Personas Profile API.


You can test your code directly from the Functions editor by entering a test event and clicking Run to make sure the function works as expected.

In the debugger panel, check the two outputs. The Error Message and the Logs.

  • Error Message - This shows the error surfaced from your function.
  • Logs - The raw log. Any messages to console.log() from the function appear here.

Creation and deployment

Once you’ve finished writing your Destination Function, click Configure to save and use the function. On the screen that appears, give the function a name, and optionally add useful details (these are displayed in your workspace). Click Create Function to finish and make your Destination Function available in your workspace.

If you’re editing an existing function, you can Save changes without changing the behavior of your deployed function. Alternatively, you can also choose to Save & Deploy to push changes to an existing function.


Your function can throw errors or Segment may encounter errors while attempting to invoke your function. You can view these errors in the “Event Delivery” tab for your Destination:

Destination Function Event Delivery tab

Errors are handled by Segment as follows:

Errors that are retried

  • “Gateway Timeout”: Your Function took too long to complete and was canceled. By default, this timeout is 5 seconds.
  • “Internal”: An error not thrown by your function code and not covered by any other error classification.
  • “Too Many Requests”: Your Function is receiving too many events and is being throttled. If this error persists for more than an hour, contact us for help.

Errors that are not retried

  • “Bad Request” is any error thrown by your code not covered by the other errors.
  • “Invalid Settings”: A configuration error prevented Segment from executing your code. If this error persists for more than an hour, contact us for help.
  • “Message Rejected”: Your code threw InvalidEventPayload or ValidationError due to invalid input.
  • “Unsupported Event Type”: Your code does not implement a specific event type (onTrack(), etc.) or threw a EventNotSupported error.

Error logs

If your function throws an error, Segment captures the event, any outgoing requests/responses, any console logs you may have printed, as well as the error itself. Segment then displays the captured error information in the “Event Delivery” tab of your Destination. You can use this tab to find and fix unexpected errors.

Destination Function error logs

You can throw an Error or custom Error and you can also add additional helpful context in logs using the console API. For example:

async function onTrack(event, settings) {
  const userId = event.userId

  console.log("userId:", userId)

  if (typeof userId != 'string' || userId.length < 8) {
    throw new Error("input user ID is invalid")

  console.log("valid userId:", userId)

  // ...

Warning: Do not log sensitive data, such as personally-identifying information (PII), authentication tokens, or other secrets. You should especially avoid logging entire request/response payloads. The “Function Logs” tab may be visible to other workspace members if they have the necessary permissions.



The permissions required to create and manage a Destination Function are separate from those required to enable it on a source.

Currently, you must be a Workspace Owner to create, edit or delete a function.

Once you create a Destination Function, you can connect it to any source in your workspace. You need to be a Workspace Owner or Source Admin.

Editing and deleting

If you are a Workspace Owner, you can manage your Destination Function from the Functions tab. Click the function to change, and the panel that appears allows you to connect, edit or delete your function.

Editing or deleting your Destination Function

Monitoring your destination function

You can use Destination Event Delivery to understand if Segment encounters any issues delivering your source data to destinations. Errors that the Function throws appear here.

Controlling what gets passed to your Destination Function

You can use Destination Filters or Privacy Controls to manage what events and, of those events, which event properties are sent to your Destination Function.

Frequently asked questions

Does Segment retry events?

Segment retries nine times over the course of four hours. This increases the number of attempts for messages, so we try to re-deliver them another 4 times after some backoff. Segment doesn’t retry if your function returns a permanent error.

Are the events guaranteed to send in order?

No. Segment cannot guarantee the order in which the events are delivered to an endpoint.

Can I create a device-mode Destination?

Functions enable you to write and deploy Cloud-mode Destinations. We’re in the early phases of exploration and discovery for supporting customer “web plugins” for custom device-mode destinations and other use cases, but this is unsupported today.

How do I publish a destination to the Segment catalog instead of my own workspace?

If you are a Partner, looking to publish your destination and distribute your App through Segment Catalog, visit the Developer Center and check out our partner docs.

This page was last modified: 27 Apr 2020

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
Create free account