Skip to main content

​
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

Every row also gets the same three views — a configuration view, a report-runner view, and an event-stream view — so the column above lists only what is specific to the category. The views are described under each category below and built from Add the Activity and Event Views.

​
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. Inbound splits again on a question worth asking early: whether the sending half is something anyone will write. A platform with an extension or plugin can send Extole-shaped events, and the tree below is the whole integration. A platform that only emits its own fixed webhook — a payment processor, most SaaS products with a webhook page and no plugin — sends what it decided to send, and the reconciliation happens inside Extole with a prehandler, described in Normalize Inbound Events with a Prehandler. The tree is identical either way; what differs is whether it is reachable. Two vocabularies meet here and must not be conflated. The trigger rule carries the name that reaches it: the platform’s wire event name, or the integration-owned name a prehandler produced from 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: REWARD 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. These three views are the baseline, not an inbound-specific set. Every integration carries a configuration view, an activity chart, and a live event feed; the category decides what the chart counts and what the feed filters to, and a reward fulfillment partner adds a fourth view on top of them.

​
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: converted 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: shipped

​
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.