Connect Reverse ETL Source to Custom Activation

This guide takes you through the steps to connect a Reverse ETL source to your Custom Activation destination and configure field mappings.

You can connect multiple Reverse ETL sources to the Custom Activation destination.

Setup

1. Set up and configure your Reverse ETL source.
2. In the Overview tab of the source page, click Add destination > Create new destination. You can also select an already-configured destination here.
3. From the list of destinations, select Custom Activation and click Continue.
4. Configure the following settings to specify how RudderStack connects to your API:

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.

5. Proceed to configure the mapping settings.

Mapping settings

This section lists the settings to correctly map data from your Reverse ETL source to the Custom Activation destination.

Specify target audience

Create the audience on your platform before entering these values. RudderStack does not create audiences at the destination for this integration.

Sync mode

RudderStack supports only Mirror mode for this integration.

On the first run, the full membership is sent to the platform. Later runs send only inserts, updates, and deletes.

Map identifiers

Map warehouse columns to each template field defined in the Custom Activation destination.

You can map two types of fields:

• Warehouse fields: Dropdown of warehouse columns
• Static fields: Specify literal values for fields configured as Static in the destination settings

Required destination fields appear with an asterisk (*) during mapping.

Advanced settings

Sync settings

RudderStack determines how and when to run a sync based on the sync schedule you set for your Reverse ETL connection.

Sync observability settings

Storing sync logs, snapshot tables, and failed records may incur additional warehouse costs.

Data hashing

The Automatically hash PII data setting lets you hash your user data before sending it to your API.

• Configure the setting to Yes if your incoming data is not pre-hashed
• Configure this setting to No if your data is already hashed

Incorrect configuration of the Automatically hash PII data setting will result in failures.

• If the Automatically hash PII data setting is configured to Yes and your data is pre-hashed, the event will fail.
• If the Automatically hash PII data setting is configured to No and your data is not pre-hashed, the event will fail.

Such events are rejected with a clear error message, for example:

Hashing is disabled but the value for field EMAIL appears to be unhashed. Either enable hashing or send pre-hashed data.

You will also see errors in the Events tab for cases that were previously marked as successful but resulted in no matches, helping you identify and fix data quality or configuration issues.

Troubleshooting