Documentation Ecommerce and inventory Unleashed

Ecommerce integration

Unleashed

  • CategoryEcommerce
  • AuthAPI credentials

Overview

Unleashed connects with an API ID and API KEY. MessageMind imports product information and can register product-created, updated and deleted webhooks when Sync Products is enabled. Signed deliveries refresh the affected product and assembled-product components. Catalog writes are buffered for five minutes after the latest update, so this is not an instant-update guarantee. A separate supported tool can read live stock for a product by name, SKU or GUID.

What MessageMind can do with it

  • Receive real-time product.created, product.updated and product.deleted webhooks from Unleashed at POST /v1/webhooks/unleashed-webhook, routed to the right tenant by SubscriptionId on the payload.
  • Verify every webhook delivery with HMAC-SHA256 of '{x-unleashed-timestamp}.{raw body}' against the stored signature key, carried in the x-unleashed-signature header, with a plus or minus 5 minute clock-skew window.
  • Suppress a duplicate EventNotificationId while the first matching request is still in flight in the same server process. The id is removed after processing; this is not durable deduplication across workers or later retries.
  • On product.created / product.updated, GET the fresh product from https://api.unleashedsoftware.com/Products with the stored API ID + API KEY (HMAC-signed querystring, api-auth-id + api-auth-signature headers, client-type: messagemind/ecomsync), with attributes included.
  • Also GET BOM component codes from /BillOfMaterials for assembled products, so a kit's components stay listed alongside the kit itself.
  • Classify each product into the AI's simpleProducts or variableProducts bucket from Unleashed's pricing combinations (a product with options becomes a variableProduct with its pricing combination; a product without becomes a simpleProduct).
  • Debounce writes with a 5-minute AI-model save buffer so a burst of back-to-back product edits coalesces into one persisted update instead of fanning out.
  • Guard the save buffer with a catalog check that rebuilds the staged lists on a fresh copy if the AI model's catalog changed since the snapshot was taken.
  • Remove deleted products from BOTH simpleProducts and variableProducts buckets by matching metadata.guid against the Unleashed product GUID.
  • Read live stock information for one product by name, SKU or Unleashed product GUID when the stock lookup tool is enabled for the connected account.

Requirements

  • An Unleashed account that can issue an API ID and an API KEY (Unleashed, Integration, Unleashed API Access).
  • A MessageMind physical-goods product catalog configured for Unleashed, with Sync Products enabled when ongoing webhook updates are needed.
  • A deployed public MessageMind webhook URL so Unleashed can deliver signed product events.

How to connect

  1. In Unleashed, open Integration, Unleashed API Access and copy the API ID and API KEY for your account.
  2. Open /integrations and choose the Unleashed card. Enter the API ID and API KEY, then save the connection.
  3. Open the integration settings and turn on Sync Products. MessageMind registers the Unleashed webhook subscription and stores the returned SubscriptionId and Signature Key automatically.
  4. Edit a product in Unleashed to verify that a signed delivery is processed. The catalog save is debounced for five minutes after the most recent buffered edit, so continuous updates can extend that delay.

Authentication and permissions

Mechanism
Two credential surfaces. (1) Outbound reads against api.unleashedsoftware.com are HMAC-signed: the querystring is HMAC-SHA256'd with the API KEY and sent as the api-auth-signature header, alongside api-auth-id (API ID) and the client-type header 'messagemind/ecomsync'. (2) Inbound webhooks are verified by recomputing base64(HMAC-SHA256(signatureKey, '{x-unleashed-timestamp}.{raw body}')) and comparing it against x-unleashed-signature in constant time, with a 5-minute clock-skew window.
Credentials
The API ID and API KEY are entered in the connection form. When Sync Products is enabled, MessageMind registers the webhook and stores the returned SubscriptionId and Signature Key on the integration; these are not additional tenant form fields.

Available data and actions

Reads

  • The full product record from GET /Products?productId={guid}&includeAttributes=true&pageSize=200 whenever a product.created or product.updated webhook fires.
  • BOM component codes from GET /BillOfMaterials for assembled products, so kit components are listed on the catalog row.
  • Every webhook body: EventType, SubscriptionId, EventNotificationId, and the Data object carrying the product GUID.

Writes

  • The AI model's eCommerce for Physical Goods product catalog, bucketed into simpleProducts and variableProducts arrays and keyed by metadata.guid (the Unleashed product GUID), updated through the debounced save buffer.
  • Vector-DB embeddings for the touched product rows, so AI retrieval sees the fresh name, SKU, attributes, pricing combinations and image on the next question.

AI agent use cases

  • Refresh product descriptions and prices from Unleashed after signed product events are processed and the catalog buffer is saved.
  • Add or remove a SKU in Unleashed and let the product event update the AI catalog without a separate manual edit.
  • Keep assembled products and their BOM component codes together in the catalog.
  • Answer a stock question using the live stock lookup for the requested product.

Configuration

  • The AI-model save buffer uses a five-minute debounce. Every additional buffered update resets the timer; persistence follows a quiet interval rather than a guaranteed five-minute deadline from the first event.
  • The catalog guard (catalogBufferGuard) checks whether the AI model's catalog changed since the snapshot was taken; if it did, the staged lists are rebuilt on the fresh copy before the save goes out.
  • Webhook signature window: plus or minus 5 minutes clock skew (CLOCK_SKEW_SEC = 300). An out-of-window delivery is rejected with x-unleashed-timestamp failures.
  • EventNotificationId dedup: an in-process Set holds the id for the lifetime of the request. A redelivery with the same EventNotificationId while the first is still in flight is acked as 'Request received' without re-processing.
  • Pricing-combinations classification: a product that Unleashed returns with a non-empty pricing combination is written to the variableProducts bucket; otherwise it goes to simpleProducts.
  • Client-type header: outbound Unleashed REST calls identify as 'messagemind/ecomsync' so Unleashed-side telemetry can distinguish MessageMind traffic.

Example workflows

Product edited in Unleashed refreshes the AI catalog

  1. An operator edits a product in Unleashed (price, description, attributes, assembled flag, etc).
  2. Unleashed POSTs product.updated to /v1/webhooks/unleashed-webhook, carrying the SubscriptionId, EventNotificationId, EventType and Data (with the product GUID). Headers include x-unleashed-signature and x-unleashed-timestamp.
  3. MessageMind looks up the Integration document by SubscriptionId; a stranger subscription is refused with 401.
  4. The signature is verified by recomputing base64(HMAC-SHA256(signatureKey, '{timestamp}.{raw body}')) and timing-safe-comparing it to x-unleashed-signature. A plus or minus 5 minute window on x-unleashed-timestamp bounds replay.
  5. MessageMind calls Unleashed back at GET /Products?productId={guid}&includeAttributes=true (and /BillOfMaterials if the product is assembled) using the stored API ID + API KEY to pull the fresh record.
  6. The product is classified (simple vs variable from its pricing combination) and the matching bucket on the AI model's physical-goods catalog is rewritten through the debounced save buffer.
  7. The updated catalog becomes available after persistence. The five-minute debounce starts again when more product edits arrive.

Product deleted in Unleashed is removed from the AI catalog

  1. Unleashed fires product.deleted with the product GUID in the Data block.
  2. After signature + subscription verification, MessageMind filters the product out of BOTH simpleProducts and variableProducts by matching metadata.guid against the Unleashed GUID.
  3. The result is persisted through the save buffer and the AI stops offering the retired product.

Limitations

  • The current scope is product sync. Stock on hand, warehouses, sales orders, purchase orders and contacts are listed in the connect modal's description but are not wired into the shipped webhook handler.
  • Only three Unleashed events drive the AI catalog today: product.created, product.updated and product.deleted. Other Unleashed events do not reach the handler.
  • Save-buffer latency is five minutes after the latest buffered update; sustained edits can postpone the save. Process failures and provider errors can also delay processing.
  • A webhook delivery older than plus or minus 5 minutes is rejected (timestamp_out_of_window), so a replay attack or a very delayed delivery is dropped rather than processed.
  • The webhook SubscriptionId is the only routing key. A tenant that deletes and re-creates its Unleashed webhook subscription needs to update the stored SubscriptionId or the deliveries will be refused as 'subscription not recognized'.
  • Deduplication is an in-flight, per-process set. It does not suppress a later redelivery after processing finishes or a concurrent delivery handled by another worker.

Troubleshooting

Unleashed reports its webhook deliveries are failing with 401 'bad webhook signature'.

Check the integration sync status. If the webhook subscription or signature key has changed outside MessageMind, repair the connection through the Sync Products setting or contact support; the normal registration stores these values automatically.

Unleashed reports 401 'subscription not recognized'.

The webhook subscription no longer matches the integration record. Check the Sync Products connection and repair the subscription through that setting or support rather than editing hidden credential fields.

A product edit in Unleashed is not showing up in the AI's answers.

Allow a quiet interval of five minutes after the latest product edit. If the change is still absent, check the integration sync status and ask support to inspect webhook validation and catalog persistence errors.

The outbound GET /Products call fails with 401 or 403.

The stored API ID + API KEY cannot sign a valid request against Unleashed. Regenerate the Unleashed API credentials in Integration, Unleashed API Access and repaste them into the Unleashed card on /integrations.

A deleted Unleashed product still appears in the AI's answers.

Confirm the webhook delivery was received (check the server logs for product.deleted with the right GUID). Deleted products are matched against metadata.guid in both buckets; a product written before metadata.guid was set would need a re-import rather than a delete to vanish.

The handler returned 200 but nothing happened.

The EventNotificationId was already in the in-process dedup Set from a near-simultaneous delivery; the retry was acked with 'Request received' without re-processing. This is the correct behaviour. If the first delivery itself did not land, check the server logs for its EventNotificationId.

Disconnect and reconnect

  • Turn off Sync Products to remove the MessageMind Unleashed webhook subscription, or disconnect the integration to remove the connection. Products already imported into MessageMind are not a promise of ongoing sync after disconnection.
  • Reconnect with a valid API ID and API KEY and enable Sync Products again when ongoing updates are needed.