Event and data reference

Every event the Conviro_AiChat module sends to Conviro, what triggers it, when it is not sent, every field, how it is retried, and what Conviro does with it. Plan §21, and §20 items 8–10 (catalog data, order data, event reference).

Sources: the module's observers (AiChat/Observer/*, AiChat/etc/events.xml), AiChat/Service/Event/*, AiChat/Service/Inventory/*, AiChat/Service/Sync/*; the backend's apps/api/src/modules/magento/magento-event-ingest.service.ts and magento-commerce-sync.service.ts. Read 2026-09-24 on feat/magento-10-10 (d3472ce2); updated 2026-09-25 for revenue attribution (514d99b0, f9e583f6) and release gate R3 (ceaaac4d API, 8791cdc4 module: customer.deleted, the trimmed order.placed, payment assist, the cart link). Behaviour marked measured was measured on the local Magento 2.4.7-p4 test stack only (see Supported versions).

Contents: Delivery model · Envelope · Common rules · Retry and dead letter · Idempotency · Catalog events · Inventory · Customer events · Order events · Cart and payment · Operational events · Identity events (1.5.0) · Plan §21 coverage · Conviro → Magento webhooks · Catalog data reference · Order data reference

Delivery model

1. A Magento observer (or a sync job) builds an envelope and inserts one row into the local table conviro_event_outbox — inside Magento's own database transaction where there is one. No network call happens in the storefront, checkout or admin request.
2. The cron job conviro_deliver_events (every minute, one process at a time via a lock) claims up to 50 due rows at a time for up to 50 seconds and POSTs each one to https://api.conviro.io/v1/api/magento/events, signed.
3. Conviro answers; the module's RetryPolicy decides what happens to the row.

Details (signature format, claim tokens, locks) are in Architecture.

Envelope

Built by Service/Event/EventFactory.php (ENVELOPE_VERSION = 1):

{
  "id": "3f0c6a8e-6f1e-4c2e-9d61-0f4c1c9e2b7a",
  "type": "order.placed",
  "version": 1,
  "occurredAt": "2026-09-24T10:15:02Z",
  "store": {
    "baseUrl": "https://shop.example.com",
    "websiteId": 1,
    "storeId": 1,
    "storeCode": "default",
    "locale": "en_US",
    "currency": "EUR"
  },
  "subject": { "type": "order", "id": "000000123" },
  "data": { "...": "per event type, below" },
  "meta": { "extensionVersion": "1.4.0", "magentoVersion": "2.4.7-p4" }
}

If the store context cannot be read, store holds only storeId (or is empty).

Common rules for every event

An event is not queued when any of these holds (EventPublisher::allows):

• the module is disabled for that store view (conviro_aichat/general/enabled), or
• no Conviro API key is saved (never connected, or disconnected), or
• the event is store-scoped — type starts with order., customer., cart., checkout. or payment. — and its store view is not selected in the setup wizard (step 4). Product and inventory events are catalog-wide and are never filtered by the store selection; customer.deleted is never held back by it either (the customer's orders may come from another, selected store view).

Each type below adds its own switch (a Sync Settings toggle). Toggles are read for the store view of the event, so a website-level override works (Configuration reference).

EventPublisher::publish() never throws: if the INSERT fails, the event is lost and a warning is logged ([Conviro] Could not queue …) — a failed sync event never fails a checkout, registration or product save.

Retry and dead letter

Service/Event/RetryPolicy.php, same for every type:

The back-off adds up to 38,550 s (about 10.7 hours) plus up to a minute of cron granularity per attempt. dead, dropped and repaired rows are purged 30 days after they were queued (conviro_purge_outbox, daily 03:23). Repair failed items (a sync job) re-queues or rebuilds dead and dropped events — see Data sync.

Ordering: the worker claims rows in id order, so events usually arrive in queue order, but a retried event can arrive after later ones. Conviro's order store applies state, status and totals only from an event at least as new (occurredAt) as the last one applied.

Idempotency

• Module: the envelope is stored once and sent byte for byte; a retry reuses the same id. A claimed batch that a crashed worker never finished becomes claimable again after 300 s.
• Conviro: MagentoEventIngestService keeps mag:evt:<tenant>:<event id> in Redis: an id already done (kept 7 days) answers 2xx duplicate with no side effect; an id another replica is processing (claim kept 5 minutes) answers 409, which the module retries. A handler that throws releases the claim and answers 5xx. For the event types whose handlers act on the world — order.placed (order attribution, cart-recovery cancellation), cart.updated (recovery scheduling), customer.created (lead), checkout.started (checkout attribution) and payment.failed (the payment-assist offer) — the claim is a database row (magento_event_receipts, migration 0227; security review R3): it holds with Redis down, so a redelivery is still a duplicate; a database error answers 5xx and the module retries. Receipts are kept 7 days. Every other type keeps the Redis gate, which fails open without Redis; those handlers are idempotent by key (KB upsert by SKU, commerce tables upserted by the store's ids).
• Coalesced types: inventory.updated (per SKU) and sync.job.progress (per job) replace a still-pending row's payload instead of queuing another; the row gets a new envelope id. A row a worker already claimed is left alone and a new row is added.

Catalog events

Switch: Sync Settings › Sync Products to KB (conviro_aichat/sync/product_sync, default off; the setup wizard's step 5 Catalog box switches it on). Read for the product's store (admin saves = store 0 = default).

product.created / product.updated

data for an enabled product (Service/Event/ProductPayloadBuilder.php):

data for a disabled product: { "sku": "…", "enabled": false } only.

product.deleted

inventory.updated

data (Service/Inventory/InventoryPayloadBuilder.php):

Customer events

customer.created

customer.updated

Measured (attribution.sh, c3374a58): not on creation, not for a name change, one event for a group change, nothing while customer data is not shared or for an unselected store view, delivered signed without a name.

customer.deleted

Measured on the local stack (privacy-deletion.sh): the customer's own customer.updated and the order / cart / payment events carrying its e-mail dropped with empty payloads, another shopper's order left pending, one customer.deleted with exactly customerId and email, delivered signed; none while no customer data is shared; sent although the store view was not selected. The backend half is covered by apps/api payment-assist.pg.spec.ts on Postgres (what is deleted, nulled, anonymised and left alone).

customer.synced (historical)

Order events

Switch: Sync Settings › Send Order Events (conviro_aichat/sync/order_events, default on), read for the order's store view. Store-scoped: nothing is sent for an order of an unselected store view.

Answers about orders in chat do not come from these events: the assistant reads the order live from Magento. The events keep Conviro's commerce_orders table current (history, and later revenue attribution) and stop cart recovery.

order.placed

Exactly these fields — each one read by a Conviro consumer (release gate R3):

Until 1.4.0 the event also carried the billing first / last name and phone, the line items (name, SKU, quantity, row total) and the customer id. No Conviro consumer read them (abandoned-cart cancellation, commerce_orders, attribution, live order lookup and leads were all checked), so they are no longer sent. Measured (privacy-deletion.sh): a real order's event carries exactly the ten fields above (no attribution from the CLI), delivered signed.

order.processing / order.completed / order.canceled / order.status_changed

order.shipped

order.refunded / order.partially_refunded

order.synced (historical)

No names, addresses, phones or line items.

Cart and payment events

Both are off by default and need two things: the toggle on for the store's website and the merchant's confirmation at default scope (Cart recovery and payment assist). Upgrading from 1.3.x holds a toggle that was already on until it is confirmed.

cart.updated

checkout.started

Measured (attribution.sh, c3374a58): only with cart recovery on and confirmed, once per checkout state, no e-mail for a guest who gave none, not for an unselected store view; observer p50 0.89 / p95 1.18 ms.

payment.failed

Measured on the local stack (payment-assist.sh, the failure event dispatched as QuoteManagement::submitQuote() does, on a real quote): nothing while off or not confirmed; the six fields from an admin / CLI request, plus the visitor and link ids from a storefront REST request; no visitor id without consent under Cookie Restriction Mode or with Revenue attribution off; delivered signed. The backend half (one offer under five parallel page views, withdrawn, expired) is apps/api payment-assist.pg.spec.ts.

Operational events

sync.job.progress

data: jobId (int), type (catalog\|inventory\|orders\|customers\|repair), status (queued\|running\|completed\|failed), processed, failed, skipped, total (int), cursor (string), createdAt, startedAt, finishedAt (string\|null), lastError (≤ 300 chars, e-mail addresses replaced by [email]), and for repair rebuilt, requeued; for orders windowDays. No customer data.

test.ping

Sent by Send test event (data: {source: "admin"}, subject store/test) and by wizard step 7 ({source: "setup-wizard"}, subject store/setup-verify). Conviro accepts and counts it.

Unknown types

Conviro answers 2xx ignored to a type it does not handle, so a newer module never dead-letters against an older backend.

Identity events (1.5.0, unreleased)

1.5.0 (unreleased), read 2026-09-27 on feat/magento-1.5.0-customer-hub. Sent only by a store that has switched signed customer identity on at least once (Signed customer identity and My orders); a store that never did has no bindings and sends nothing.

identity.bindings_revoked

No customer id, e-mail or session id. Not yet measured end to end (the identity-bridge.sh scenario that delivers it signed through the real outbox needs the Docker stack); unit tests cover the module side (BindingRevocationTest, PasswordChangeRevocationTest) and the Conviro ingest.

Plan §21 coverage

Every type of plan §21's baseline is emitted by 1.4.0: customer.updated and checkout.started (f9e583f6, above) were the last two. customer.deleted (release gate R3) goes beyond it.

Conviro → Magento webhooks

Conviro also calls the store: POST https://<store>/conviro/webhook/receive (Controller/Webhook/Receive.php). Conviro subscribes the store to these event types when it registers: lead.captured, lead.created, contact.created, session.started, plus webhook.test (Conviro's "send test", data.test = true).

The store verifies X-Webhook-Signature: t=<unix>,v1=<hex> (HMAC-SHA256 of "<t>.<raw body>" with the webhook secret, ±300 s), checks data.tenantId against its own tenant id, accepts only the known types, and records the delivery once (replay key = SHA-256 of "<t>.<verified HMAC>" — canonical, so re-spelling a captured header does not make it new again; table conviro_inbound_event, purged hourly after a day). Answers: 401 bad/missing signature, 400 malformed, 403 tenant mismatch, 422 unsupported event, 200 once (200 duplicate for a replay), 500 if processing threw (the replay key is released so Conviro's retry can apply it).

The store records these events in conviro_webhook_log (event name, direction in, HTTP status, error code — no payload); a request that fails the signature check is only counted — one rejected row per reason and minute, its hits column saying how many (1.4.0) — so forged POSTs cannot flood the table. It dispatches the Magento event conviro_webhook_received with conviro_event and conviro_data, for the merchant's own code to act on. The module itself takes no other action.

Catalog data reference

What Conviro keeps per product (one knowledge-base entry per SKU, built by apps/api/src/modules/magento/magento-product-kb-content.ts for both the event path and the nightly REST pull):

Product · SKU · Price · In Stock · Variants · Specifications · Summary · Description · URL, capped at 6,000 characters.

• Price is the price attribute labelled with the store's base currency (or unlabelled when it cannot be established). There is no "Special Price" line. The price a shopper pays is answered live from products-render-info in the shopper's store view (final or regular, display currency).
• In Stock comes from MSI salability when the store has MSI, else the legacy stock item.
• Variants and Specifications are the blocks the module rendered with Magento's attribute labels; a product event stores them with the entry, and the nightly REST pull reuses them for that product because the integration's REST permissions cannot resolve attribute labels.
• The KB is keyed by SKU, not by store view: text is the default store view's (re-sync) or the saving store's (events).

The optional nightly REST pull (02:00 server time, only for workspaces with KB sync enabled) lists products with visibility 2, 3 or 4 and deactivates KB entries of products no longer listed — only after a complete listing.

Order data reference