Custom Activation Setup Guide

Use this guide to set up a Custom Activation destination in RudderStack.

To sync a saved audience to your Custom Activation destination, see How to Sync Audiences to Custom Activation.

Setup

1. Go to Collect > Destinations > New Destination.
2. Search and select Custom Activation.
3. Creating a source is optional. Click Continue to skip this step.
4. Configure the following settings to specify how RudderStack connects to your API and complete the setup:

Audience delivery API configuration

Authentication

Except for No authentication, every method below requires Need authentication support? to be on — you then link an account in the account card.

Set up Client Credentials

1. Turn on Need authentication support? and choose Client Credentials in the account card.
2. Create an account with the account fields, or select an existing one, and link it to the destination.
3. To change settings or rotate the secret, open the account from the destination’s account card and select Edit account. The Client secret is masked and optional — leave it blank to keep the stored secret, even when you change other settings. The current token stays in use until it expires, so your new settings take effect at the next token refresh.

If you run a hybrid or self-hosted data plane, upgrade rudder-server to a version that supports Client Credentials accounts before you link one. Cloud data planes need no action.

The first event for a new Client Credentials account triggers the token request. That first attempt fails and retries automatically once the token is issued — no action needed.

Set up Authorization Code

1. Turn on Need authentication support? and choose Authorization Code in the account card.
2. Copy the Redirect URI shown in the account form and register it in your provider’s app settings. It’s the same URI in all regions, so you only need to register one.
3. Create an account with the account fields, complete the authorization in the popup, and link the account to the destination.
4. Use Re-authorize when the provider asks you to reconnect. Authorization Code accounts can’t be edited; to change settings, create a new account and relink the destination.

Enter OAuth account fields

Fill in these fields when creating an account. Don’t put client secrets in URLs, Extra token parameters, or Custom headers.

OAuth requirements

Your provider’s token endpoint must accept a standard OAuth 2.0 token request and return JSON with an access_token. RudderStack sends it to your API as an Authorization: Bearer header and refreshes it automatically when it expires. Authorization Code accounts without a refresh token can’t be refreshed; use Re-authorize when delivery stops.

Endpoint configurations

Configure how RudderStack adds, updates, and removes audience members:

Action-specific settings

Each action’s (add/update/remove record) settings follow the same structure.

HTTP method and endpoint path

The resolved URL is the base URL plus the evaluated endpoint path.

Batch size

Request body template

Define the JSON body sent to your API. The template follows JSONata syntax.

Templates are validated when you save the destination. An invalid syntax is rejected with an error that identifies the action and issue.

A sample request body template is shown below:

{
  "audience_id": $$.connection.audienceId,
  "elements": [$$.records.{
    "userIds": [
      {"idType": "SHA256_EMAIL", "idValue": sha256_email},
      {"idType": "GOOGLE_AID", "idValue": google_aid}
    ],
    "firstName": first_name,
    "lastName": last_name,
    "nested": {
      "org": "static_value"
    }
  }]
}

Global objects available at runtime

Allowed operations

• Object and array construction
• Path expressions ($$.records, $$.connection.audienceId)
• Iteration with { ... } — for example, $$.records.{ "email": email, "user_id": user_id }
• String, number, and boolean literals
• Number() casting where needed, for example,$number($$.connection.audienceId)

Template example

A template for generic batched members is shown below:

{
   "audienceId": $$.connection.audienceId,
   "users": [$$.records.{
    "email": email,
     "user_id": user_id
  }]
}

Template fields

After you define a template, RudderStack extracts field names referenced under $$.records and lists them under Template fields. Click Refresh to re-scan the template, or Manage fields to configure each field.

If you rename or remove template fields after syncs exist, make sure to update mappings on each affected sync manually.

See Troubleshooting for more information.

Request preview

Use Fetch preview to build a sample HTTP request from test records.

Preview doesn’t call your API or fetch an OAuth token. It renders the Authorization header with a masked value, so you can check the method, URL, and body without exposing a credential.

1. Choose how many sample records to include (for example, 1 record).
2. Edit sample data if needed.
3. Click Fetch preview to see the resolved method, URL, headers, and JSON body.

Troubleshooting

Next steps

To sync a saved audience to your Custom Activation destination, see How to Sync Audiences to Custom Activation.