Webhooks
Overview
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.
We use the phrase near real time to describe the fact that under normal conditions, a Violet webhook will be generated within seconds of an update within an ecom platform. However, this is not guaranteed; Shopify for example says they can take up to 10 minutes to send us the update webhook. Then on top of that, depending on our own system load, we can take a number of minutes to process it on our side before ending with sending out our own webhook to you. So while normally you will see updates coming through fairly quickly there are definitely known scenarios where it can take 10-15 minutes before the webhook ends up going out. Please note that is not a hard upper bound, just and example of how long it could take when our systems are under load.
Therefore, Violet webhooks are not strictly real time, and instead have a small but variable time delay between an update in an e-commerce platform and the webhook delivery to your servers.
Webhook Events
Violet publishes the following Webhook events that your service can subscribe to for near-real time updates:
See our docs on Simulating Webhooks docs to get real example webhooks sent to you. This is a great way to view what real payloads look like.
Orders
Catchall event for any updates made to an order. An example of this might be a correction to a shoppers shipping address. These typically have no impact on the lifecycle of the order.
If you are looking to listen to only specific updates, the following webhook events can be subscribed to:
Will trigger when an order is placed by submitting a cart checkout.
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.
Will trigger when part or all of an order has been refunded, without order cancellation or item return.
Will trigger when all or part of an order has been returned, with or without a refund.
Will trigger when all or part of an order has been cancelled, with or without a refund.
Merchants
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.
Will trigger when a merchant disconnects from your app.
Will trigger when a existing disabled merchant in Violet is updated to enabled status. May include X-Violet-Reason
header with APP_INSTALLED_ON_PLATFORM
reason.
Will trigger when a existing enabled merchant in Violet is updated to disabled status. May include X-Violet-Reason
header with APP_UNINSTALLED_FROM_PLATFORM
or MERCHANT_PLATFORM_PLAN_INACTIVE
reason.
Will trigger if the merchant has any INCOMPLETE
or NEEDS_ATTENTION
items during the connection health check. Example here.
Will trigger once a merchant has completed all required items to begin processing orders, that is, their connection health check has all items marked COMPLETE
. Uses the same format as MERCHANT_NEEDS_ATTENTION
Offers
Will trigger when a new offer is created.
Will trigger when an update is made to an offer.
Will trigger when an offer is no longer available for purchase.
Product Sync
Will trigger when the merchant’s products begin syncing. Payload example here.
Will trigger when the merchant’s product sync is completed. Example here.
Will trigger if the merchant’s product sync fails. Example here.
Webhook Headers
Violet provides headers to all webhook calls that help understanding and filtering the events by your service.
Default headers
Signed hmac with your app secret for security validation.
Event topic as defined in Webhook Events section.
Unique event id. This allows your service to process an event just once in case of duplicated delivery.
Related entity id. For example, an offer webhook will have the Violet Offer Id here.
Entity’s length (bytes) in the event body.
Triggered webhook id.
Additional headers
Certain events may have additional headers specific to that webhook type. Current additional headers:
Related order id.
Related bag id.
Additional context as to what triggered the event.
Custom headers
Violet also allows your service to define key-value pairs as headers to be sent together with your webhooks. This allows you to define specific headers to use in any way you desire in your system.
Please refer to Managing Webhook Headers.
Handling Webhooks
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.
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 Related 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
- Offer Updated
- Offer Removed
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.
Merchant Related 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:
APP_INSTALLED_ON_PLATFORM
APP_UNINSTALLED_FROM_PLATFORM
MERCHANT_PLATFORM_PLAN_INACTIVE
MERCHANT_CREDENTIAL_INVALID
MERCHANT_PLATFORM_SCOPES_INVALID
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.
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.
Was this page helpful?