Overview

An integration is a campaign whose component tree connects Extole to an outside system. Every integration belongs to a category, and the category decides the component model, the resources the integration needs, and which build sequence to follow in Create an Integration with the Management API.

Three questions place any platform:

1. Does the platform send activity to Extole? The integration is inbound.
2. Does Extole send activity to the platform? The integration is outbound.
3. Does Extole order something of value from the platform when a participant earns a reward? The integration is reward fulfillment, which is outbound in direction but a distinct model.

Answer all three before creating anything. A platform that only receives Extole activity needs no business events, a platform that only sends activity needs no webhooks or credentials, and only a platform that fulfills rewards needs reward suppliers.

Category Summary

Inbound Integrations

An inbound integration turns a platform's own event names into canonical Extole business events. The platform posts to the Events API from a server-side extension, a middleware service, or a file feed, and Extole maps each arriving event to a reusable business-event component. Building the campaign is only half of it: see Send Platform Events to Extole for the sending half that runs in the platform.

Two vocabularies meet here and must not be conflated. The platform's wire event name belongs on the trigger rule that listens for it. The business event carries the canonical name the rest of the platform already understands — converted, shipped, canceled, account_opened, and the other names bundled programs use. Never rename a business event to match a platform's wire name.

Data capture is the integration. A business event with an empty data socket produces an event with no transaction identifier, no person key, and no value, so nothing downstream can deduplicate, attribute, reward, or report on it.

An inbound integration contains:

root
└── integration                 integration-v10.x
    ├── partner configuration settings
    ├── businessEvents          MULTI_SOCKET → business-event-v10.0
    │   └── canonical event
    │       ├── triggerRules    → input_event rule carrying the platform's event names
    │       └── data            → one component per captured field
    └── views                   MULTI_SOCKET → view-v10.0
        └── configuration       config-view-v10.0

Inbound integrations need no reward supplier, webhook, or client key. Creating those resources for completeness leaves credentials and unused resources that someone later has to reconcile.

Outbound Integrations

An outbound integration forwards Extole program activity to the platform. Child controllers listen for Extole events and call the platform's endpoints through webhooks, authenticated with a webhook client key that holds the platform's API credential.

Most outbound platforms ship as maintained library sources that an account can duplicate, which is the same action the Install button performs on the Partners page. The install is the starting point, not the finished integration: the library carries defaults for every account, while the partner page defines the finished shape for this platform — which forwarded events apply, which endpoints the integration calls, which settings hold credentials, and any reusable data template that marketing campaigns attach.

An outbound integration contains:

root
└── integration                 integration-v10.x
    ├── one child per forwarded Extole event
    └── data-item template      partner data component type (when marketing campaigns attach partner actions)

The partner page's product description is the specification for that tree. The activity it says the integration forwards is the complete set of children, the endpoints it says Extole calls are the complete set of webhooks, and a statement that program campaigns attach partner data to their events means the integration carries a typed data template. A library source ships the union of what every account might want, so the install usually has more children and fewer webhooks than the finished integration.

Alongside the tree, the integration owns one webhook per platform endpoint. Each webhook is tagged by purpose, and the integration component holds a WEBHOOK_ID setting per webhook whose buildtime expression resolves the webhook by that tag. Marketing campaigns attach partner actions through those settings rather than by webhook identifier.

Outbound integrations do not replace a marketing program's business events. Installing one never supersedes a program's converted or shipped event, because the integration reports activity rather than producing it.

Reward Fulfillment Integrations

A reward fulfillment integration orders something of value from the platform when a participant earns a reward: a gift card, a prepaid card, points, or a payout. Extole calls the platform's order endpoint, the platform returns an order result, and the reward moves to fulfilled or fails and is retried.

The direction is outbound, but the model is distinct because the platform sells products rather than accepting messages. Each product a client can offer becomes a reward supplier — a configured source of rewards carrying its own value, program identifiers, and payment terms. A client that offers two card types has two reward suppliers drawn from the same integration.

That produces two campaigns instead of one:

• The integration campaign holds the partner component, its credential and account settings, its webhooks, and its views.
• A support campaign of type CONFIGURATION holds one supplier template per product variant. Templates live apart from the integration because a client installs them repeatedly — a different denomination or program number each time — and each install must be its own configured supplier.

A reward fulfillment integration contains:

integration campaign
└── integration                 integration-v10.x
    ├── credential and account settings
    ├── rewardSuppliers         MULTI_SOCKET → the partner's own supplier type
    ├── views                   MULTI_SOCKET → config, report-runner, event-stream views
    │   ├── configuration       credential and account settings
    │   ├── reward suppliers    surfaces the rewardSuppliers socket
    │   ├── reward activity     report-runner-view-v10.0
    │   └── reward events       event-stream-view-v10.0
    └── one REWARD webhook per order endpoint, plus a status check

support campaign                CONFIGURATION
└── one supplier template per product variant
    └── a reward supplier element tagged with its product variant

The Supplier Type and Its Templates

The socket filter needs a type that means "a supplier belonging to this partner", so the integration defines its own component type whose parent is the platform's reward-supplier type. Filtering on the platform type instead would let any partner's supplier install into this integration.

Each template owns one reward supplier. Beyond value and currency, the supplier carries a data map holding the identifiers the order call needs — program number, financial account, payment terms — and a tag naming the product variant. That tag is load-bearing twice over: the webhooks resolve the suppliers they serve by it, and the template's own supplier-id setting resolves its element by it.

Value is either fixed or a percentage of the event that earned the reward. Templates usually expose that as a toggle, with the supplier's face-value algorithm resolved from it at build time and minimum and maximum bounds applied to the calculated amount.

Reward Webhooks

These webhooks are type REWARD, not the generic type an outbound integration uses, and they do not fire for every reward. Each one filters on two things at once:

• The reward suppliers it serves, resolved at build time by collecting the supplier elements under the integration's children that carry the product tag.
• The reward state it acts on — the earned state for an order call, the fulfillment-failed state for a status check.

Getting that pair wrong is the failure mode worth guarding against. A webhook with no supplier filter attempts to fulfill every reward in the account through one partner endpoint; a webhook with no state filter re-orders rewards that are already fulfilled.

Order webhooks pair a request handler that builds the order from reward and person data with a response handler that fulfills the reward, schedules a retry, or fails it. A status-check webhook exists because some products do not complete synchronously — a physical card is manufactured and shipped — so it polls on an escalating retry schedule that can run for weeks, far longer than the minutes-to-hours schedule an order call uses.

Views

Reward integrations carry more than a configuration tab, because the people using them want to see fulfillment working: a configuration view for the credential and account settings, a view surfacing the supplier socket that reports itself incomplete while no supplier exists, a report-runner view charting reward activity, and an event-stream view filtered to reward event types and the partner's app type.

Bidirectional Integrations

A platform that both sends outcomes and receives rewards or coupons combines the two models. Build the inbound half first and prove it, then add outbound resources only when the destination endpoint, authentication contract, retry and idempotency behavior, configuration surface, and a program action that produces the outbound event all exist.

A reward-supplier socket does not connect a platform. A reward supplier models fulfillment inventory or behavior, and a webhook is the HTTP transport. Creating either without the rest of the program wiring produces configuration that looks complete and does nothing.

Placing a New Platform

Read the platform's own developer documentation and the partner page in this documentation set, when one exists, before choosing. Signals that place a platform quickly:

Discovery decides the category, not habit. Rebuilding a maintained outbound platform from the custom integration template produces a campaign that looks related and performs none of the platform's webhook or credential work.

Related Documentation

• Create an Integration with the Management API
• Send Platform Events to Extole
• Integrating with Extole
• Key Concepts