Skip to main content
This page is one part of the Management API integration guide. Start at Create an Integration with the Management API for the build paths and the creation contract.

​
Gate Outbound Resources

This section applies to an inbound custom build that someone proposes to extend outbound. The webhooks and credential an outbound library install ships with are already part of its finished shape and are not gated here. Inbound event mapping does not require a reward supplier, webhook, or webhook client key. Create outbound resources only when all of these conditions are true:
  • The requested scope includes a defined outbound use case.
  • A program action or reward rule produces the event or reward.
  • The destination endpoint and authentication contract exist.
  • Retry, idempotency, error handling, and ownership are defined.
  • The integration or program has a configuration surface for required values.
  • The path can be tested before it is enabled.
A reward-supplier socket does not connect a partner. A reward supplier models fulfillment inventory or behavior. A webhook is the HTTP transport. Creating either resource without the other program wiring leaves unused external resources and misleading configuration. When outbound scope is later removed, archive resources in dependency order:
  1. Disable the webhook.
  2. Remove webhook filters and component references.
  3. Archive the webhook.
  4. Remove reward-supplier references from rules and components.
  5. Archive the reward supplier.
  6. Remove and archive the client key after all active references are gone.
  7. Remove unused component settings and sockets.
  8. Publish and verify the resulting campaign.

​
Validate Before Publishing

Inspect the latest campaign and built components. Confirm:
  • Campaign type is INTEGRATION and program type is integration.
  • When the build must appear as an installed integration, the integration model component is a child of the root, is owned by this client, and carries both internal:type:integration and internal:self-managed. Read the component back and check the tags rather than assuming the create request applied them.
  • The root and integration model components exist, the model component carrying an integration-v10.x type.
  • businessEvents accepts business-event-v10.0.
  • Each canonical event is a duplicated reusable template.
  • Every partner wire event in scope reaches a business event, and no two outcomes that a report would need apart share one. Count the business events against the wire events and account for any difference: a failed payment and a refund arriving as the same event passes every other check on this page.
  • Each event has an input_event rule with the expected partner event names — or, where a prehandler renames the inbound event, with the names the prehandler produces. Those names belong to this integration and are not the canonical outcome names the business events carry: a rule listening for converted matches every converted event in the account, so the partner’s raw webhook reaches programs the integration never consulted. Normalize Inbound Events with a Prehandler covers why.
  • Whoever sends the inbound event can actually send the shape the rules expect. When the sender is the partner’s own webhook rather than something built for this integration, a prehandler exists, is enabled, carries at least one condition, and is referenced to the integration component. A disabled prehandler, or one with an empty condition list, passes every structural check on this page and still leaves the integration inert. Where more than one prehandler participates, read the evaluated order as well: a chain that is structurally sound still fails when a prehandler runs ahead of the one it depends on. Normalize Inbound Events with a Prehandler covers all of them.
  • Every event carries an email address, or an identity the account can actually reach. Where a prehandler flattens the payload, read its actions and confirm the email is among the keys it emits: a partner nests the address away from the transaction fields, so an integration that captures the amount and the order and not the address is the normal outcome rather than an unusual one, and nothing about it fails.
  • Whoever configures the partner is given the endpoint. The configuration view’s setup instructions render the URL the partner posts to, computed from the campaign — not a sentence naming the Extole event endpoint without producing it. Everything else on this list can be correct while the integration receives nothing, because the last step belongs to a person who was never told where to send it.
  • Each event has its own reporting names and no two events share a noun or rate name.
  • No alias appears on more than one business event.
  • Every business event has data components in its data socket, and every data component has the intended source expression and key type.
  • The eight required integration display settings hold usable values, not merely present ones. Read each from /v1/components/built and check it against the value convention in Create the Integration Campaign and Component Model:
  • Read from /v1/components/built, logo on the integration component and rewardSupplierLogo on every supplier template each hold an absolute URL. An empty value, or one still showing a spel@buildtime: expression, is a tile that renders the grey placeholder.
  • No legacy custom controller duplicates a reusable business event.
  • views accepts view-v10.0.
  • The configuration view is attached to the model component.
  • settingsToDisplay references existing parent settings.
  • The views socket holds the three baseline views: the configuration view, a report-runner-view-v10.0, and an event-stream-view-v10.0. Two views is an integration missing the surfaces a marketer opens to see whether it is working. A reward fulfillment build carries a fourth, the reward-suppliers configuration view, and the baseline three are not optional there either.
  • Read from /v1/components/built, reportRunnerId on the report-runner view and eventStreamId on the event-stream view each resolve to an identifier rather than null. A null value means the element was never created, or was attached to the integration component instead of the view that reads it. Neither shows up as a failed call.
  • Every column named in reportColumnsMapping is one the report runner’s mappings expression produces, and the event stream carries its filters. A view with a chart mapping and a null runner, or a stream with no filters, renders a tab that exists and says nothing. Add the Activity and Event Views covers both.
  • No unrequested reward supplier, webhook, client key, or socket exists.
Publish the explicit version that was validated: INTEGRATION Treat a successful publish as model validation, not end-to-end verification. Nothing above proves an event reaches a step, and two of the pieces this guide creates — a prehandler script and a data component’s valueExpression — are stored without ever being executed. Send a real payload and read the resulting step before reporting the integration as working.

​
Offer to Connect the Integration to a Program

A finished integration receives partner events and turns them into business events inside its own campaign. The marketing programs in the account still run on the business events their theme shipped with — a generic converted on the friend journey, for example — which listen for the platform’s default events, not the partner’s. Until those two halves are joined, the integration produces activity that no program acts on. Close the build by proposing two things and doing neither without an answer:
  1. Publish the integration campaign, which is what makes the inbound endpoint accept events.
  2. Install the integration’s business events into a marketing campaign.
For the second, name the campaign candidates, list the partner events by canonical name, and say for each one whether it supersedes an event the program already has or adds one the program lacks. A partner converted supersedes the theme’s converted on the same journey; shipped and canceled are usually additions. On approval, work through the target campaign’s journey socket:
  • Duplicate each partner business event from the integration into the socket that holds the program’s equivalent event, using the same duplication call as the rest of this guide with the integration’s component as the source.
  • Remove the superseded default event after its replacement is installed, so the journey does not carry two events with the same canonical name.
  • Add the partner events the program lacks into the same socket.
  • Refresh the campaign version between mutations, then read the built campaign and confirm the journey lists the expected events in lifecycle order.
This changes a program’s funnel, so it is never a silent step. Name the campaign and the events before touching them, and report afterwards which events were replaced, which were added, and what the program’s journey now contains.

​
Reference Structure for an Order Lifecycle Integration

Most commerce platforms map onto the same three canonical events. Use this as the starting shape and adjust it to the events the partner actually emits: A complete integration of this shape contains one integration model component, three business events, one input_event rule per event, one data component per captured field on each event, and three views: a configuration view displaying the partner account setting and the computed setup instructions, a report-runner view charting the events the integration produces, and an event-stream view feeding them live. It is inbound-only: no reward-supplier socket, reward webhook, or webhook client key. Platforms with a different lifecycle keep the same construction and change the event set. A lending or account platform maps to account_opened, application_approved, and funded; a subscription platform maps to converted, renewed, and canceled. The canonical name always describes the business outcome, never the partner’s transport name.