Overview

An inbound integration has two halves: an integration campaign inside Extole maps arriving events onto canonical business events (see Build a Packaged Integration with the Management API), and server-side code in the platform sends those events to the Events API.

Send events server-side. A token in storefront templates, theme files, or browser code is published to every site visitor. Platforms whose events can only be produced in the browser use the JavaScript SDK instead.

When You Would Send Events

Situation	The sender
A commerce platform reports purchases, shipments, or cancellations	An extension or plugin
A platform with no plugin surface reports account or subscription activity	A middleware service
Records arrive as files (CSV over SFTP or upload)	The File Integration extension — not this Events API sender
Records arrive in batches from a scheduled job you host	A middleware service
A partner emits only its own fixed webhook	No sender — a prehandler reshapes it in Extole

What the Sender Needs

Hold these as configuration, not constants, so a token or label changes without a code release:

Setting	Purpose
Event endpoint	`https://api.extole.io/v6/events` in production.
Access Token	A server-side token from the Security Center, authorized to submit events. Store it encrypted.
Program label	The installed integration’s current label, from its configuration view.
Platform identifier	The store URL, site identifier, or tenant that produced the event.
Status or state mapping	The platform’s own status identifiers that mean the event happened, read per installation rather than copied from another.
Request timeout	A short network timeout for the delivery worker.
Retry policy	Backoff and maximum attempts for temporary failures.

How to Send

Send events from a worker, not the hook that observed them: the hook persists a sanitized record and returns, the worker delivers it. An Extole timeout or network failure must never fail a checkout, block an order-status transition, or slow a page the customer waits on.

Build the Payload

The event carries the platform’s event name and a flat data object of the mapped fields:

{
  "event_name": "platform_order_created",
  "data": {
    "email": "customer@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "order_id": "10042",
    "total": 42.5,
    "customer_id": "customer-9001",
    "store_url": "https://shop.example.com",
    "labels": "example-integration"
  }
}

labels goes inside data and holds the integration’s current program label, not one copied from another account.
Name every source key exactly as the partner page does; data components read keys by name, so a renamed key arrives with that field missing rather than an error.
Send what the integration maps and nothing more. Payment-card data, passwords, session identifiers, and unrelated metadata have no mapped destination.

Choose the Endpoint

Use /v6/events for a new sender: it responds synchronously, so the worker can verify what Extole did with each event. For sustained high-volume delivery, evaluate /v6/async-events, where acceptance no longer means the event has been processed — update the worker’s verification and retry behavior. Some partner pages document /v5/events, a still-supported path.

curl --request POST "https://api.extole.io/v6/events" \
  --header "Authorization: Bearer $EVENTS_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data @event.json

A valid submission returns 200 with a JSON body carrying the person_id. An empty 204 No Content means the request is not reaching the Events API — check the host.

Retry and Deduplicate

Extole answers an accepted submission with a 2xx. Retry network failures, 429, and retryable 5xx responses; authentication and validation failures fail identically on every attempt. Expect the same event more than once, because platforms re-fire hooks and replay status history — 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.
Validate and normalize emails, identifiers, URLs, and numeric values before sending.
Verify HTTPS certificates.
Allow token rotation without reinstalling the extension.

How to Test

Send one event synchronously. The response returns a person_id; read that person’s steps:

curl --get "https://api.extole.io/v5/persons/$PERSON_ID/steps" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --data-urlencode "campaign_ids=$CAMPAIGN_ID" \
  --data-urlencode "names=converted"

Confirm the step carries the canonical event name, not the platform’s; the transaction identifier and value match the source record; person keys resolve; and resending the same source identifier produces a duplicate outcome, not a second conversion. Repeat for every event.

No Business Event Appears

A 2xx means accepted, not matched. Check in order:

The current program label is inside data.labels.
The platform event name matches the name on the integration’s input_event trigger rule exactly.
The integration campaign is published.
The event carries enough identity data to resolve a person.
The source keys match the ones the integration’s data components read.

Integration Overview

Extole AI Tools

Platform Integrations

Partners

Building Packaged Integrations

Solutions

Operational Tasks

Troubleshooting

Send Platform Events to Extole

Overview

When You Would Send Events

What the Sender Needs

How to Send

Build the Payload

Choose the Endpoint

Retry and Deduplicate

Protect the Integration

How to Test

No Business Event Appears

​Overview

​When You Would Send Events

​What the Sender Needs

​How to Send

​Build the Payload

​Choose the Endpoint

​Retry and Deduplicate

​Protect the Integration

​How to Test

​No Business Event Appears

​Related Documentation

Overview

When You Would Send Events

What the Sender Needs

How to Send

Build the Payload

Choose the Endpoint

Retry and Deduplicate

Protect the Integration

How to Test

No Business Event Appears

Related Documentation