Handling Webhooks

Overview

Properly handling webhooks allows your solution to be up to date faster. Please find bellow tips and specifics that will allow you to have a better experience consuming Violet webhooks.

Good Practices

We recommend any incoming webhook event to be processed in a separate thread than it was received. This allows the request to be handled faster, with a simpler and less error prone solution and ultimately avoiding the webhook being disabled due to constant failures.

Within first 10 seconds:

  1. Receive webhook event.

  2. Add request to a queue (Database, Kafka, SQS, etc).

  3. Respond with a 2XX response.

In a separate thread:

  1. Get request from queue.

  2. Validate hmac.

  3. Process data.

Big Webhook Requests

Violet webhook request bodies always contain the related entity data regardless of its size. In a scenario that the client cannot consume the request entirely, it's possible to ignore the body and request it directly later on.

All requests contain X-Violet-Entity-Length, X-Violet-Webhook-Id and X-Violet-Event-Id headers that allows a client to check the entity length in bytes and retrieve the data if finds it necessary.

Please refer to Webhook Events to request a specific webhook body.

Failing Webhooks

In case the remote endpoint provided in your webhook is failing, in order to protect both yours and Violet's systems, here's what may happen:

  1. The webhook events will be attempted to be delivered 10 times, using back off retries over the course of 24 hours, after which point they are considered FAILED.

  2. If attempts to send events to a webhook's remote endpoint fail more than 50 times in a 30 minute window, the delivery attempts for that webhook will be temporarily disabled for 1 hour. If the problem persists, the webhook delivery attempts will be disabled again for 3 hours, and any subsequent failures will be disabled for a maximum of 24 hours.

  3. If the webhook remote endpoint is still failing after the 3 rounds of temporary disablement, the webhook will be DISABLED entirely until the channel re-activates it. No webhook events will be created after the webhook is disabled.

Every time deliveries are temporarily disabled or webhooks are disabled due to delivery issues, you will receive an email stating the reason.

To avoid having webhooks disabled, we strongly recommend following webhook good practices.

Events

Order Webhooks

The body of the webhook sent to your remote endpoint will be a fully composed Order object. This order object will contain all bags and SKUs from the originally placed order. To determine which bag in order the event that triggered the webhook occurred on, you can consume the X-Violet-Bag-Id header which will contain the ID of the bag that has been updated.

Order webhooks will trigger when relevant order events occur in the external commerce platforms. Relevant events can include the following:

  • Order Shipped

  • Order Cancelled

  • Order Refunded

  • Order Returned

If you are using external payments, events related to cancellations, refunds, or returns may require some or all of the amount paid by the shopper to be returned to them. Information regarding any refunded amounts will be available in the order data.

Offer Webhooks

These are universal offer webhooks that are triggered for any Offer related to your Channels connected Merchants with no possibility of filtering by products.

There is an upcoming solution currently called Product Collections that will allow Channels to create collections of products and subscribe to them. This will result in Channels being triggered to a smaller set of offers. More to come on this soon.

The body of the webhook sent to your remote endpoint will be a fully composed Offer object. This offer object will contain all details of the offer, including related SKUs.

Offer webhooks will trigger when changes occur to offers in Violet platform. The events are categorized in the following:

  • Offer Created (Deprecated. Use OFFER_ADDED instead.)

  • Offer Updated

  • Offer Removed

  • Offer Added

  • Offer Deleted

OFFER_ADDED vs. OFFER_CREATED

The OFFER_ADDED event provides a more comprehensive and accurate notification for when an offer becomes available for purchase. It is the recommended event to use for all offer availability notifications.

  • OFFER_ADDED: This event triggers whenever an offer becomes available for purchase. This includes newly created offers that are immediately published, existing offers that are updated to a "published" status, and pre-existing offers that become available when a merchant and channel first connect.

  • OFFER_CREATED: This event only fires when Violet first ingests an offer from a merchant's ecommerce platform. It does not notify you of pre-existing offers that become available or offers that are published after their initial creation.

Deprecation Notice

The OFFER_CREATED webhook event is deprecated and will be fully sunset on September 30, 2025. All integrations should migrate to the OFFER_ADDED event to ensure comprehensive and reliable offer availability notifications.

OFFER_DELETED vs. OFFER_REMOVED

  • OFFER_DELETED: This event is sent when an Offer is permanently removed from the system. Listen to this event to reliably track permanent deletions.

  • OFFER_REMOVED: This event is sent whenever an app loses access to an offer. This can happen when:

    • An offer is unpublished (PUBLISHED → NOT_PUBLISHED).

    • An offer is marked for deletion.

    • A merchant disconnects from an app (triggering this event for all their published offers).

Collection Webhooks

The body of the webhook sent to your remote endpoint will be a fully composed Collection object. This collection object will contain all details of the collection, excluding offers within it.

Collection webhooks will trigger when changes occur to collections in Violet platform. The events are categorized in the following:

  • Collection Created

  • Collection Updated

  • Collection Removed

  • Collection Offers Updated

When processing Collection Offers Updated webhooks we recommend consuming the Get Collection Offers IDs endpoint to check all offers IDs in the collection.

Product Sync Webhooks

All Product Syncs share a payload in the following format. All fields except id, merchant_id, status and total_products are optional, and may be omitted entirely depending on the platform. Possible values for status are NOT_STARTED, PENDING, IN_PROGRESS, COMPLETED, FAILED, and ABORTED.

Product Sync Payload Example
{
  "taxonomy_synced": false,
  "webhooks_created": true,
  "id": 144,
  "merchant_id": 10149,
  "status": "COMPLETED",
  "abort": false,
  "total_products": 5008,
  "total_products_synced": 4519,
  "resync_required": false,
  "date_last_synced": "2023-04-24T18:01:55+0000"
}

Collection Sync Webhooks

The body of the webhook sent to your remote endpoint will be a CollectionSync object. This collection sync object will contain all details of the sync.

Collection sync webhooks will trigger when merchant collections are being sync in Violet platform. The events are categorized in the following:

  • Collection Sync Started

  • Collection Sync Completed

  • Collection Sync Failed

Collection Sync Payload Example
{
  "status": "IN_PROGRESS",
  "merchant_id": 10069
}

Merchant Webhooks

Merchant Enabled / Disabled Webhooks

The body of MERCHANT_ENABLED and MERCHANT_DISABLED webhooks sent to your remote endpoint will be a Merchant object when merchant status changes between ACTIVE and DISABLED in Violet.

A X-Violet-Reason header may be included with reason of the status change. Possible values include:

  1. APP_INSTALLED_ON_PLATFORM

  2. APP_UNINSTALLED_FROM_PLATFORM

  3. MERCHANT_PLATFORM_PLAN_INACTIVE

  4. MERCHANT_CREDENTIAL_INVALID

  5. MERCHANT_PLATFORM_SCOPES_INVALID

Merchant Enabled Payload Example
{
  "id": 10189,
  "name": "sample-store",
  "platform": "SHOPIFY",
  "store_url": "sample-store.myshopify.com",
  "custom_store_url": "sample-store.com",
  "status": "ACTIVE",
  "default_currency": "USD",
  "default_country_code": "US",
  "default_state_code": "WA",
  "default_language_code": "EN",
  "commission_rate": 10,
  "distribution_type": "PRIVATE",
  "referral_source": "VIOLET",
  "connection_status": "CONNECTED"
}

Merchant Needs Attention/Complete Webhooks

Merchant Needs Attention and Merchant Complete webhooks use the following format. Possible statuses are COMPLETE, INCOMPLETE, NEEDS_ATTENTION, NOT_APPLICABLE, and ERROR.

Merchant Needs Attention/Complete payload example
{
  "merchant_id": 10054,
  "merchant_name": "WooCommerce's Store",
  "platform": "WOOCOMMERCE",
  "store_url": "woocommerce.violet.io",
  "distribution_type": "PRIVATE",
  "connection": {
    "results": {
      "is_connected": true,
      "has_shipping_methods": true
    },
    "status": "COMPLETE"
  },
  "scope_validation": {
    "results": {
      "valid": true,
      "missing_scopes": []
    },
    "status": "COMPLETE"
  },
  "sync_status": {
    "status": "NOT_APPLICABLE"
  },
  "invalid_products": {
    "status": "NOT_APPLICABLE"
  },
  "offers_published": {
    "results": {
      "sync_complete": false,
      "count": 8
    },
    "status": "COMPLETE"
  },
  "payout_account": {
    "results": {
      "id": 10043,
      "account_id": 10052,
      "account_type": "MERCHANT",
      "external_id": "acct_2JIpDR2c7q6FBT2u",
      "country_code": "US",
      "status": "COMPLETE",
      "date_created": "2021-02-11T23:03:59+0000",
      "date_last_modified": "2023-02-15T15:15:05+0000",
      "details": {
        "account_holder_name": "John Doe",
        "business_tax_id_provided": true,
        "tos_accepted": true,
        "website_url": "violet.io",
        "payouts_enabled": true,
        "payments_enabled": true,
        "has_payout_account": true,
        "currently_due": [],
        "eventually_due": [],
        "past_due": [],
        "pending_verification": []
      }
    },
    "status": "COMPLETE"
  },
  "migration_account": {
    "status": "ERROR",
    "error": {
      "message": "Unexpected paymentServiceAccountType: null"
    }
  },
  "commission_rate": {
    "default_rate": 10,
    "overrides": [],
    "status": "COMPLETE"
  },
  "terms_of_service": {
    "results": [],
    "status": "NEEDS_ATTENTION"
  },
  "channel_connections": {
    "total_connected": 5,
    "status": "COMPLETE"
  }
}
PreviousSimulating Webhook EventsNextCurrent Platforms

Last updated

Was this helpful?