Syncs

Sync webhooks notify your application about the status of product and collection synchronization operations. These events are essential for tracking when merchant catalogs are being updated and when fresh data is available.

Understanding Sync Events Lifecycle

Initial Merchant Onboarding: When a merchant first connects to your application, sync events fire in this sequence:

  1. MERCHANT_CONNECTED event fires

  2. PRODUCT_SYNC_STARTED fires shortly after (first catalog sync begins)

  3. PRODUCT_SYNC_COMPLETED fires when initial sync finishes (catalog now available)

  4. If collections are enabled: COLLECTION_SYNC_STARTED → COLLECTION_SYNC_COMPLETED

Ongoing Syncs: After the initial sync, these events continue to fire regularly:

  • Scheduled syncs: Violet performs periodic syncs based on platform and configuration (e.g., daily)

  • Manual syncs: Triggered via API or dashboard

  • Platform-triggered syncs: Some platforms notify Violet of changes, triggering immediate syncs

Important: Sync events fire throughout a merchant's entire lifecycle, not just during onboarding. Each sync operation (initial or recurring) generates a new set of STARTED → COMPLETED/FAILED events.

Product Sync Events

PRODUCT_SYNC_STARTED

Trigger: When the merchant's products begin syncing. This occurs:

  • Shortly after initial merchant connection (first sync)

  • During scheduled periodic syncs (e.g., daily)

  • When manually triggered via API or dashboard

  • When the platform notifies Violet of catalog changes

Use Case: Subscribe to this event to:

  • Display "syncing" status to users

  • Pause catalog-dependent operations

  • Log sync start times

  • Track sync frequency and patterns

  • Notify internal teams of sync initiation

Example Payload: See the Product Sync Webhooks example in the Handling Webhooks guide.

For New Merchants: This is one of the first events you'll receive after MERCHANT_CONNECTED. The merchant's catalog is not yet ready for use—wait for PRODUCT_SYNC_COMPLETED.

PRODUCT_SYNC_COMPLETED

Trigger: When the merchant's products sync is completed successfully. This signals that:

  • All product data has been fetched from the merchant's platform

  • Offers have been created or updated in Violet

  • The catalog is ready for querying and display

  • Any offer-level webhooks (OFFER_CREATED, OFFER_UPDATED) have been sent

Use Case: Monitor this event to:

  • Refresh catalog data in your system

  • Update product listings and search indexes

  • Trigger post-sync operations (indexing, analytics, caching)

  • Notify users that new products are available

  • Calculate sync duration and performance metrics

  • Enable catalog-dependent features for new merchants

Example Payload: See the Product Sync Webhooks example in the Handling Webhooks guide.

Critical: This is your definitive signal that catalog data has been refreshed and is ready for use. Always wait for this event before querying a merchant's catalog after PRODUCT_SYNC_STARTED.

For New Merchants: Once you receive this event after initial connection, the merchant's products are available for display and purchase in your platform.

PRODUCT_SYNC_FAILED

Trigger: If the merchant's products sync fails due to:

  • Platform API errors or downtime

  • Invalid merchant credentials

  • Network connectivity issues

  • Platform rate limiting

  • Merchant account issues

Use Case: Monitor this event to:

  • Alert internal teams to sync issues immediately

  • Notify merchants of sync problems with actionable guidance

  • Log error details for debugging and support

  • Trigger retry mechanisms (with exponential backoff)

  • Track sync reliability metrics per merchant and platform

  • Escalate repeated failures

Example Payload: See the Product Sync Webhooks example in the Handling Webhooks guide.

Note: The webhook payload typically includes error information to help diagnose the failure.

For New Merchants: If the initial sync fails, the merchant's catalog will not be available. You should proactively reach out to resolve the issue before they can begin selling.

Collection Sync Events

COLLECTION_SYNC_STARTED

Trigger: When the merchant's collections begin syncing.

Use Case: Subscribe to this event to:

  • Display collection syncing status

  • Track collection sync operations

  • Coordinate with product syncs

  • Log sync initiation

COLLECTION_SYNC_COMPLETED

Trigger: When the merchant's collections sync is completed successfully.

Use Case: Monitor this event to:

  • Refresh collection data

  • Update collection navigation

  • Trigger collection-based operations

  • Update collection indexes

  • Verify collection structure

Important: Collections and products may sync independently. Don't assume that a product sync also updates collections.

COLLECTION_SYNC_FAILED

Trigger: If the merchant's collections sync fails.

Use Case: Monitor this event to:

  • Alert teams to collection sync issues

  • Notify merchants of problems

  • Log error details

  • Implement fallback strategies

  • Track collection sync reliability

Related Documentation

Best Practices

  1. Don't fetch data during STARTED events - Wait for the COMPLETED event before refreshing catalog data to ensure you get the complete updated dataset.

  2. Track sync pairs - Match each STARTED event with its corresponding COMPLETED or FAILED event using the merchant ID to track sync duration and success rates.

  3. Handle partial syncs - Products and collections sync independently. A product sync may complete while a collection sync is still in progress or fails.

  4. Implement sync status tracking - Maintain a sync status for each merchant to avoid triggering operations on stale catalog data.

  5. Set timeouts - If you don't receive a COMPLETED or FAILED event within a reasonable timeframe after STARTED, investigate and potentially alert.

  6. Batch post-sync operations - After receiving COMPLETED events, batch your catalog refresh operations to avoid overwhelming your systems with individual offer/collection updates.

  7. Monitor sync failures - Track FAILED events closely and implement alerting for repeated failures, which may indicate merchant integration issues.

  8. Use sync events for caching strategies - Leverage sync completion events to invalidate and refresh catalog caches efficiently.

Webhook Headers

Sync webhooks include the default webhook headers, which contain:

  • X-Violet-Entity-Id - The identifier for the sync operation

  • X-Violet-Topic - The event type (PRODUCT_SYNC_STARTED, etc.)

  • X-Violet-Event-Id - Unique event identifier for idempotency

Common Integration Patterns

Full Catalog Refresh

PRODUCT_SYNC_STARTED → Set status "syncing"
PRODUCT_SYNC_COMPLETED → Fetch all offers → Update catalog → Index data
COLLECTION_SYNC_COMPLETED → Fetch collections → Update navigation

Sync Monitoring

PRODUCT_SYNC_STARTED → Record start time → Update dashboard
PRODUCT_SYNC_COMPLETED → Calculate duration → Log metrics
PRODUCT_SYNC_FAILED → Log error → Alert team → Notify merchant

Coordinated Sync Operations

PRODUCT_SYNC_COMPLETED + COLLECTION_SYNC_COMPLETED → Both complete → Trigger full refresh
Either FAILED → Log failure → Use cached data → Alert team

Coordinating with Other Events

Sync events typically occur alongside merchant and offer events:

Initial Merchant Onboarding

MERCHANT_CONNECTED → Connection established
PRODUCT_SYNC_STARTED → Catalog sync begins
OFFER_CREATED (for each product) → Products being added
PRODUCT_SYNC_COMPLETED → All products synced
COLLECTION_SYNC_STARTED → Collections sync begins (if enabled)
COLLECTION_SYNC_COMPLETED → Collections available
MERCHANT_COMPLETE → Merchant ready for orders

Scheduled Sync Flow

PRODUCT_SYNC_STARTED → Daily sync begins
OFFER_UPDATED (for changed products) → Product changes detected
PRODUCT_SYNC_COMPLETED → Sync finished

Merchant Re-enablement

MERCHANT_ENABLED → Merchant reactivated
PRODUCT_SYNC_STARTED → Re-sync triggered
OFFER_UPDATED (all offers) → Offers re-enabled
PRODUCT_SYNC_COMPLETED → Catalog current

Failed Sync Recovery

PRODUCT_SYNC_STARTED → Sync initiated
PRODUCT_SYNC_FAILED → Error encountered
(Wait for retry interval)
PRODUCT_SYNC_STARTED → Retry begins
PRODUCT_SYNC_COMPLETED → Success

Monitor sync events alongside merchant and offer events for complete catalog lifecycle visibility.

Sync Timing Considerations

  • Initial merchant connection: Expect sync events shortly after merchant connection completes

  • Scheduled syncs: Violet performs periodic syncs based on platform and configuration

  • Manual syncs: Syncs can be triggered manually through the API or dashboard

  • Platform-triggered syncs: Some platforms notify Violet of changes, triggering immediate syncs

PreviousCollectionsNextPayout Accounts

Last updated

Was this helpful?