Webhooks

Clione receives webhooks from Shopify and BigCommerce to keep product, collection, and page data in sync. All incoming webhooks are verified using HMAC-SHA256 signatures.

Inbound Platform Webhooks

These are webhooks Clione subscribes to on the source platform.

Shopify

Topic	Fires when
products/create	A product is created in Shopify
products/update	A product is updated
products/delete	A product is deleted
orders/create	A new order is placed (used for learning signals)
orders/paid	An order is marked as paid (used for learning signals)

Signature: X-Shopify-Hmac-Sha256 header, base64-encoded HMAC-SHA256 of the raw body, signed with SHOPIFY_API_SECRET.

BigCommerce

Scope	Fires when
store/product/created	A product is created
store/product/updated	A product is updated
store/product/deleted	A product is deleted
store/order/created	A new order is placed (learning signals)
store/order/statusUpdated	An order status changes (learning signals)

Signature: X-BC-Webhook-Signature header, hex-encoded HMAC-SHA256 of the raw body, signed with BC_WEBHOOK_SECRET.

Signature Verification

Both handlers use crypto.timingSafeEqual() for constant-time comparison.

Production behavior: If the platform secret is not configured, webhooks are rejected with HTTP 500. Unsigned webhooks are never accepted in production.

Development behavior: If the secret is not configured and NODE_ENV !== 'production', webhooks are accepted with a warning log.

Outbound Webhooks (Planned)

Clione-initiated webhooks to notify external systems of events.

Topic	Fires when
product.synced	A product is synced from the platform into Clione
product.enriched	A product's enrichment completes (success or failure)
product.manually_edited	A user overrides AI fields via the dashboard Edit tab
product.rolled_back	A user restores a past enrichment version
faq.submitted	A storefront submits a FAQ via the public form
faq.approved / faq.rejected	Admin reviews a submitted FAQ
enrichment.bulk_completed	A bulk re-enrichment finishes

Signature (planned)

All outbound webhooks will be signed with HMAC-SHA256 using a per-tenant secret (rotatable from the dashboard). Headers:

• X-Clione-Signature — HMAC
• X-Clione-Event — topic name
• X-Clione-Timestamp — epoch ms, reject anything older than 5 min

Retry policy (planned)

• On non-2xx response: exponential backoff (1s, 5s, 30s, 2m, 10m, 1h, 6h)
• After 7 failures, mark endpoint as degraded + notify the tenant admin
• Dead-letter queue for manual replay from the dashboard

Until outbound webhooks ship, you can poll GET /api/v1/{platform}/products?updated_since=<ISO> to pick up changes.