For API Reference go to Webhooks


Through the use of webhooks your application can subscribe to events that occur within Violet. Webhooks are an efficient alternative to continuously polling for anticipated events or changes to data.

As an example, a webhook can notify your app when on orders status has changed or a merchant has connected to your app. By being made aware of these events in near-real time your app can instantly react to updates and perform any necessary actions.

Webhook Events

ORDER_SHIPPED - Will trigger when an order is fulfilled by a merchant through their commerce platform. This will usually add additional information to the order like tracking data.

ORDER_REFUNDED - Will trigger when part or all of an order has been refunded, without order cancellation or item return.

ORDER_RETURNED - Will trigger when all or part of an order has been returned, with or without a refund.

ORDER_CANCELLED - Will trigger when all or part of an order has been cancelled, with or without a refund.

ORDER_UPDATED - Catchall event for any updates made to an order outside of the common ones listed above. An example of this might be a correction to a shoppers shipping address. These typically have no impact on the lifecycle of the order.

MERCHANT_CONNECTED - Will trigger when a merchant completes the Violet Connect onboarding experience and is successfully connected to your app. The data sent to the remote endpoint will contain all non-sensitive data related to that merchant, including their name and merchant ID.

Handling Order Related 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. In the event that the update applies to a single item in the order, an X-Violet-Sku-Id header will also be present. When present this value will map to sku_id property of the line item.

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

Any events in the area of 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.

Universal product webhooks are not available due to the massive volume of product related events going through the Violet system, a volume that will only continue to grow. Without a mechanism for channels to tell Violet which product's it's interested in, your application would be bombarded with events for every product updated across the entire system, even if you have no interest in the product.

There is an upcoming solution to this problem that we are calling Product Collections. Channels will be able to create collections of products and through this subscribe to them. More to come on this soon.

Updated 19 May 2022
Did this page help you?