Part of the partner integration guide.

Overview

An Extole to Partner integration forwards Extole program activity to a partner platform. Start from a maintained source when it includes the required controllers and webhooks. When the source contains only display metadata, add the controller-backed delivery yourself. Substitute the component name, endpoints, and tag namespace from the partner page throughout. Build a Partner Integration with the Management API covers the constraints and shared mechanics every build follows.

When You Would Build One

You want	Partner platform	The install adds
Extole activity to trigger a partner message	Marketing automation, messaging	A message-trigger webhook and its `WEBHOOK_ID` setting
Extole activity to keep partner profiles or audiences current	Customer data platform	An ingestion webhook and its `WEBHOOK_ID` setting
Extole program activity in a partner’s reporting	Analytics	An ingestion webhook and its `WEBHOOK_ID` setting
A marketing campaign to attach partner actions to its own events	Any partner in this direction	A typed data-item child of the integration component

Do not add Partner to Extole business-event scaffolding to this install. A partner that orders gift cards, prepaid cards, points, or payouts uses the distinct reward fulfillment model.

Before You Start

Parameter	Value
`TOKEN`	Server-side access token authorized to manage campaigns, components, and webhooks.
`EXTOLE_API_HOST`	Production host for those calls.
`PARTNER_COMPONENT_NAME`	Maintained component name from the partner page.
`SOURCE_COMPONENT_ID`	The Extole-owned maintained source from the duplicatable listing, when one exists.
`INTEGRATION_COMPONENT_ID`	The installed or newly created integration component, for component-scoped webhooks.
`CAMPAIGN_ID`, `CAMPAIGN_VERSION`	The integration campaign and its current version. Every change creates a new version, so read the version again before each versioned call.
`CONTROLLER_ID`	The controller that listens for one class of Extole activity.
`WEBHOOK_ID`	The outbound connection invoked by a controller action.

Read the partner page first — it names the finished tree, the endpoints, and the tag namespace — and inspect any matching source before choosing the build path. Without a complete source, create the container from Create the Integration Campaign and Component Model, then add the controller-backed delivery described below.

Choose the Build Path

List the duplicatable sources whose name matches the partner exactly, accepting every integration-v10.* revision — Install the Maintained Source shows the query — then inspect the integration component and its children. The integration component’s integration-v10.* type tells you the version, not whether the source delivers anything. A complete maintained source has all of the following:

An integration component tagged internal:self-managed
Child controllers for the activity it forwards
Webhook actions with event-specific data
The webhooks and credential settings those actions reference

When the source carries only display metadata, use the controller-backed path below. Choose each controller’s trigger by the kind of activity it forwards:

Activity	Trigger
Share-link creation	An event trigger with `event_type` set to `SHAREABLE`. The standard event name is `advocate_code_created`.
A program outcome such as `converted`	An event trigger with `event_type` set to `STEP`.
A fulfilled reward	A reward-event trigger with `reward_states` set to `FULFILLED`, created through `.../controllers/{controller_id}/triggers/reward-events`.

Share-link creation and shared are distinct. The first creates a shareable and exposes its link; the second records a share action. Forwarding a fulfilled reward to a messaging or analytics partner is not the same as a partner that supplies the reward. A gift card, prepaid card, points, or payout provider uses Build a Reward Fulfillment Integration.

How to Build

Confirm the Finished Shape

The partner page’s product description specifies the finished tree. Each statement it makes maps to something the install must carry:

What the partner page states	What the install must carry
The activity the integration forwards	One child per listed activity, and none forwarding activity the page omits
The partner endpoints Extole calls	One webhook per endpoint, each tagged by purpose
That program campaigns attach partner data to their own events	A typed data-item child of the integration component
That the integration exposes its partner connections as settings	One `WEBHOOK_ID` setting per webhook, resolved by tag
The account URL and credential the partner requires	The matching settings on the integration component

Read that mapping as exhaustive rather than as a minimum, and apply it to an integration already in the account as much as to a fresh install. A maintained source ships the union of what every account might want, so it commonly installs children the page does not list and only one of the webhooks it names. A maintained source may not ship the report-runner and event-stream views every integration carries. Read the installed views socket and add whichever is missing from Add the Activity and Event Views.

Create Controller-Backed Outbound Delivery

Skip this section when the maintained source already contains the requested controllers and payloads. Create one controller per event class or payload contract. Attach the controller to the integration component with component_ids; do not modify a marketing campaign to host integration behavior. Create a controller:

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CONTROLLER",
    "name": "send_converted_to_partner",
    "scope": "PRIVATE",
    "enabled": false,
    "enabled_on_states": ["LIVE", "PAUSED"],
    "selectors": ["TARGET"],
    "journey_names": ["participant"],
    "component_ids": ["'"${INTEGRATION_COMPONENT_ID}"'"],
    "data": [
      {
        "name": "recipient_email",
        "value": "spel@runtime:context.person.email",
        "scope": "PRIVATE",
        "persist_types": ["STEP"]
      }
    ]
  }' \
  "${EXTOLE_API_HOST}/v2/campaigns/${CAMPAIGN_ID}/version/${CAMPAIGN_VERSION}/controllers"

Record the returned controller identifier as CONTROLLER_ID. Refresh the campaign version, then add a step-event trigger:

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_phase": "MATCHING",
    "trigger_name": "Converted",
    "event_names": ["converted"],
    "event_type": "STEP"
  }' \
  "${EXTOLE_API_HOST}/v2/campaigns/${CAMPAIGN_ID}/version/${CAMPAIGN_VERSION}/controllers/${CONTROLLER_ID}/triggers/events"

For share-link creation, use the same endpoint with event_type set to SHAREABLE and read the link from context.causeEvent.shareable.link. Create every controller and trigger while the path is disabled. Then publish and create the component-scoped webhook, as described in Publish, Then Attach Component-Scoped Webhooks, and attach it to the controller through Attach the Webhook Action. Take field names and identity rules from the partner page.

Create Missing Component Types

A typed child needs its component type first, and a partner page can require a type the account has never used. Read the type, and create it only when the read finds nothing:

curl -s -H "Authorization: Bearer ${TOKEN}" \
  "${EXTOLE_API_HOST}/v1/component-types/${PARTNER_COMPONENT_NAME}-data"

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"'"${PARTNER_COMPONENT_NAME}"'-data","display_name":"Partner Data Item","schema":"{}"}' \
  "${EXTOLE_API_HOST}/v1/component-types"

Omit parent. An empty types array leaves an untyped component, which satisfies no socket filter and no template lookup.

Install the Maintained Source

An install is POST /v1/components/{SOURCE_COMPONENT_ID}/duplicate without target_campaign_id: omitting the target campaign creates a new root integration campaign that copies the source tree, including its webhooks and child controllers. Send a body carrying at least one property, such as component_display_name. List the candidates before duplicating anything:

CANDIDATES=$(curl -s -H "Authorization: Bearer ${TOKEN}" --get \
  "${EXTOLE_API_HOST}/v1/components/duplicatable" \
  --data-urlencode "version_state=PUBLISHED" \
  --data-urlencode "show_all=true" \
  | jq --arg name "${PARTNER_COMPONENT_NAME}" \
      '[.[] | select(.name == $name)
             | select(any((.types // [])[]; startswith("integration-v10")))]')

jq -r '.[] | "\(.id)\t\(.types | join(","))"' <<< "${CANDIDATES}"

Choose the Extole-owned source.

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"component_display_name":"Partner"}' \
  "${EXTOLE_API_HOST}/v1/components/${SOURCE_COMPONENT_ID}/duplicate"

Reshape the Install

The reshape uses these calls, each needing a campaign version read immediately beforehand:

Action	Call
Delete an installed child	`DELETE /v2/campaigns/{campaign_id}/version/{version}/components/{component_id}`
Create a child	`POST /v2/campaigns/{campaign_id}/version/{version}/components`
Add or change a setting	`POST /v2/campaigns/{campaign_id}/version/{version}/components/{component_id}/settings`
Create a webhook	`POST /v6/webhooks`
Publish the campaign	`POST /v2/campaigns/{campaign_id}/version/{version}/publish`

Bring the installed tree to the partner page’s shape in one pass:

Delete the installed children the partner page does not keep.
Create the children it adds, including any typed data template.
Remove parent settings that belonged to a deleted child, such as a trigger-event-name setting whose controller is gone.
Set one WEBHOOK_ID setting per partner endpoint, resolved by webhook tag rather than by identifier, so the setting survives a rebuild:

javascript@buildtime: (function() { var filteredElements = Java.from(context.getComponent().createElementsQuery().withType('WEBHOOK').withTag('internal:partner:message-trigger').list()); return filteredElements && filteredElements.length > 0 ? filteredElements[0].getId() : null; })();

Filter on the purpose tag exactly one webhook carries — here internal:partner:message-trigger, matching the webhook below. Never use a shared tag such as internal:partner, which matches every webhook the integration owns. A partner data template is a typed child of the integration component, created through component_ids with no socket. Its install expression anchors the source component’s unanchored step data onto the target event:

javascript@installtime:const sourceData = Java.from(context.getSourceComponent().getUnanchoredStepData());
let targetSteps = Java.from(context.getTargetComponent().getSteps());
const stepName = context.getVariableContext().get("step");

if (stepName !== undefined && stepName !== null) {
    targetSteps = targetSteps.filter(function (step) {
        return step.getName() === stepName;
    });
}


if (targetSteps.length) {
    for (var i = 0; i < sourceData.length; i++) {
        targetSteps[0].anchor(sourceData[i]);
    }

    return;
}

Publish, Then Attach Component-Scoped Webhooks

Publish the campaign once before creating any webhook whose name or URL expression calls context.getComponent(), and create those webhooks with component_ids naming the integration component. The reshape cannot complete without that publish, so get any release approval first.

A published integration campaign has no supported route back to a draft: there is no stop or unpublish action, and archiving takes the integration out of use entirely.

Publishing validates every webhook the campaign already owns, so keep a valid placeholder host in any account-URL setting that feeds a webhook URL. The maintained source’s own default is one. Set enabled to false while a webhook points at that placeholder — enabled, it sends live program data to a host that should never receive it, unsigned when the client key is also missing. Enabling it is the step that puts the partner connection into service. POST /v6/webhooks:

{
  "name": "javascript@buildtime:context.getComponent().getName() + '_message_trigger'",
  "url": "javascript@buildtime:context.getVariableContext().get('partnerRestUrl') + '/partner/endpoint/path'",
  "type": "GENERIC",
  "default_method": "POST",
  "enabled": false,
  "client_key_id": "javascript@buildtime:context.getVariableContext().get('clientKeyId')",
  "request": "javascript@runtime:context.createRequestBuilderWithDefaults().withUserAgent('partner-Extole-Integration/1.0').build();",
  "response_handler": "javascript@runtime:(function(){ var statusCode = context.getWebhookDispatchResultEvent().getResponseStatusCode(); if (statusCode >= 200 && statusCode < 300) { return 'OK'; } if (statusCode == null || statusCode === 429 || statusCode >= 500) { return 'RETRY'; } context.log('Partner rejected webhook request with status ' + statusCode); return 'OK'; })()",
  "retry_intervals": [1, 30, 60],
  "tags": ["internal:partner:message-trigger", "internal:partner"],
  "component_ids": ["INTEGRATION_COMPONENT_ID"]
}

Record the returned webhook identifier as WEBHOOK_ID. Name each webhook for the endpoint it calls: an ingestion endpoint and a message-trigger endpoint are separate webhooks with separate tags. Keep the broad internal:partner tag for listing every webhook the integration owns. Where the account URL setting may lack a scheme, build the URL expression to add https://.

Attach the Webhook Action

Refresh the campaign version after creating the webhook, then attach the action to its controller. Map the complete partner payload here rather than leaving a generic request body for later:

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "quality": "HIGH",
    "enabled": false,
    "webhook_id": "'"${WEBHOOK_ID}"'",
    "data": {
      "person_identifier": "spel@runtime:context.person.email",
      "activity_name": "extole_converted",
      "activity_time": "spel@runtime:context.causeEvent.eventTime"
    }
  }' \
  "${EXTOLE_API_HOST}/v2/campaigns/${CAMPAIGN_ID}/version/${CAMPAIGN_VERSION}/controllers/${CONTROLLER_ID}/actions/webhooks"

Keep the controller, action, and webhook disabled until the credential, request handler, payload mapping, and response handling are complete.

Complete the Request and Response Handlers

The default request handler serializes the webhook action’s data as a JSON body, uses the configured method and URL, and applies the client key’s default authentication. A PASSWORD key adds an Authorization: Bearer header. Write a custom request expression when the partner requires a distinct authentication header, body envelope, URL, method, or idempotency key. Build the request from the webhook action data and the client key, following the contract on the partner page. Do not use createRequestBuilderWithDefaults() when its default authentication differs from the partner’s requirement. The response handler returns:

OK when processing is complete
RETRY when Extole should use the configured retry intervals

Without a response handler, Extole retries non-2xx responses. Add one when the partner contract distinguishes retryable responses such as 429 or 5xx from terminal 4xx configuration or payload errors. Log the terminal status and the minimum response detail needed to diagnose the rejection; do not log credentials or the full participant payload. A webhook is ready when its request handler produces the partner’s required body and authentication and its response handler follows the partner’s retry contract. Keep it disabled until both are verified.

Attach the Credential

Create the webhook client key once you have the partner’s API secret, then set the credential setting on the integration component. A missing credential does not block the build: leave the setting null and track it as outstanding.

Error Handling

Response	Cause	What to do
`missing_request_body`	The duplicate request had no body.	Send a JSON object with at least one property, such as `component_display_name`.
Unrecognized property	The body used `display_name`.	Use `component_display_name`.
`invalid_null`	`target_campaign_id` was sent as null.	Omit the attribute. An install creates a new campaign by leaving it off.
`invalid_component_reference`	A webhook calling `context.getComponent()` was created before the campaign was published.	Publish once, then create the webhook with `component_ids`.
Campaign validation rejects the publish	An account-URL setting that feeds a webhook URL is empty or not a valid host.	Keep a valid placeholder host there.
Webhook setting evaluates to `null`	The `WEBHOOK_ID` expression filters on a tag no webhook carries, or several webhooks share the tag and `[0]` is arbitrary.	Give each webhook its own purpose tag.
The installed component is the wrong source	The listing returns the maintained source plus copies installed in client accounts, in no reliable order.	Choose the Extole-owned source by owner and type.
A typed child is rejected	Its component type does not exist in the account.	Create the component type first; do not fall back to an empty `types` array.
An integration source has a current type but no controllers or webhooks	The source is partner metadata, not a complete outbound implementation.	Build the controller-backed path.
The partner rejects authentication	The default key processor uses a header the partner does not accept.	Build the request explicitly with the partner’s required authentication header.

How to Test

A 2xx on the duplicate call means the source tree was copied, not that the install matches the partner page. Read the campaign and its /v6/webhooks entries back, then confirm:

The tree matches the partner page: one child per activity the page lists, and no child forwarding activity it does not.
Every typed child carries its type.
Every requested activity has the matching controller trigger: SHAREABLE, STEP, or a FULFILLED reward event.
Every controller has a webhook action with the complete partner payload.
Each webhook exists with its tags and its resolved URL.
Each WEBHOOK_ID setting resolves to a webhook identifier rather than null.
Request and response handlers match the partner’s authentication, body, success, and retry contracts.
enabled is true on every webhook whose real URL and credential are both configured, and false on the rest.

Trigger each Extole event the integration forwards and confirm the partner endpoint receives the expected payload. Enable only the paths whose destination and credential are ready.

Integration Overview

Extole AI Tools

Platform Integrations

Partners

Building Partner Integrations

Solutions

Operational Tasks

Troubleshooting

Build an Extole to Partner Integration

Overview

When You Would Build One

Before You Start

Choose the Build Path

How to Build

Confirm the Finished Shape

Create Controller-Backed Outbound Delivery

Create Missing Component Types

Install the Maintained Source

Reshape the Install

Publish, Then Attach Component-Scoped Webhooks

Attach the Webhook Action

Complete the Request and Response Handlers

Attach the Credential

Error Handling

How to Test

​Overview

​When You Would Build One

​Before You Start

​Choose the Build Path

​How to Build

​Confirm the Finished Shape

​Create Controller-Backed Outbound Delivery

​Create Missing Component Types

​Install the Maintained Source

​Reshape the Install

​Publish, Then Attach Component-Scoped Webhooks

​Attach the Webhook Action

​Complete the Request and Response Handlers

​Attach the Credential

​Error Handling

​How to Test

​Related Documentation

Overview

When You Would Build One

Before You Start

Choose the Build Path

How to Build

Confirm the Finished Shape

Create Controller-Backed Outbound Delivery

Create Missing Component Types

Install the Maintained Source

Reshape the Install

Publish, Then Attach Component-Scoped Webhooks

Attach the Webhook Action

Complete the Request and Response Handlers

Attach the Credential

Error Handling

How to Test

Related Documentation