Skip to main content

​
Overview

An inbound integration has two halves. Inside Extole, an integration campaign maps arriving platform events onto canonical business events — see Create an Integration with the Management API. Outside Extole, something in the platform has to send those events. This page is the sending half, and it applies to any platform that can run server-side code: an ecommerce extension, a plugin, a middleware service, or a scheduled job. Sending happens server-side. An event carries an access token, and any token placed in storefront templates, theme files, or browser code is published to everyone who visits the site. Platforms whose events can only be produced in the browser belong on the JavaScript SDK instead.

​
What the Sender Needs

Hold these as configuration rather than constants in code, so a token rotates and a program label changes without a code release: Status identifiers are per-installation configuration on most platforms. Read them from the platform being integrated rather than copying numeric identifiers from another installation, where the same number means something else.

​
Do Not Block the Platform’s Own Workflow

Send events from a worker, not from the hook that observed them. The hook’s job is to persist a sanitized record and return; a separate worker delivers it. An Extole timeout or a network failure must never fail a checkout, block an order-status transition, or slow a page the customer is waiting on.

​
Build the Event Payload

An event carries the platform’s own event name and a flat data object holding the fields the integration maps: https://api.extole.io/v6/events Two details in that payload are the ones that go wrong. labels belongs inside data, and it holds the current program label from the integration view rather than a value copied from another account. And every source key is read by name: the integration’s data components look for the keys the partner page names, so a renamed key arrives as an event with that field missing rather than as an error. Send what the integration maps and nothing more. Payment-card data, passwords, session identifiers, and unrelated metadata have no mapped destination and become a liability the moment they are stored.

​
Choose the Endpoint

Events go to https://api.extole.io, the same host as Extole’s other server-side calls — retrieving a person, reading rewards, and the Management API. Use /v6/events while building the sender: it responds synchronously, so the worker can verify what Extole did with each event. For sustained high-volume delivery, evaluate /v6/async-events and update the worker’s verification and retry behavior for asynchronous processing, since acceptance no longer means the event has been processed. Partner pages that document /v5/events describe a still-supported path; prefer /v6/events for a new sender. data A sender that receives 204 No Content with an empty body is not talking to the Events API. The endpoint answers a valid submission with 200 and a JSON body carrying the person_id; treat an empty 204 as a misrouted request and check the host before assuming the events were accepted.

​
Retries and Duplicates

Extole answers an accepted submission with a 2xx. Network failures, 429, and retryable 5xx responses are worth another attempt; authentication and validation failures are not, because they fail identically on every attempt. Expect the same event more than once. Platforms re-fire hooks and replay status history, so one lifecycle event often reaches the sender several times. Extole deduplicates on the field mapped as the unique partner event key, so a replay resolves to the same outcome rather than a second conversion.

​
Protect the Integration

  • Restrict sender configuration to platform administrators.
  • Keep the access token out of templates, browser code, logs, and event data.
  • Redact authorization headers and request bodies in transport logs.
  • Validate and normalize emails, identifiers, URLs, and numeric values before sending.
  • Verify HTTPS certificates.
  • Allow token rotation without reinstalling the extension.

​
Verify What Arrives

Send one event synchronously and follow it through to the business event it produced. The response returns a person_id; read that person’s steps for the campaign: labels Confirm that the step carries the canonical event name rather than the platform’s, that the transaction identifier and value match the source record, that the person keys resolve, and that sending the same source identifier twice produces a duplicate outcome rather than a second conversion. Repeat for every event the integration accepts, not only the first one.

​
When Extole Accepts the Event but No Business Event Appears

A 2xx means the event was accepted, not that it matched anything. Check, in this order:
  1. The current program label is inside data.labels.
  2. The platform event name matches the name on the integration’s input_event trigger rule exactly.
  3. The integration campaign is published.
  4. The event carries enough identity data to resolve a person.
  5. The source keys match the ones the integration’s data components read.