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.
Webhook Events
Violet publishes the following Webhook events that your service can subscribe to for near-real time updates:
Orders
ORDER_UPDATED
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:
ORDER_COMPLETED
Will trigger when an order is placed by submitting a cart checkout.
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.
Merchants
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.
MERCHANT_DISCONNECTED
Will trigger when a merchant disconnects from your app.
MERCHANT_ENABLED
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.
MERCHANT_DISABLED
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.
MERCHANT_NEEDS_ATTENTION
Will trigger if the merchant has any INCOMPLETE
or NEEDS_ATTENTION
items during the connection health check. Example here.
MERCHANT_COMPLETE
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
OFFER_CREATED
This event is being deprecated. Will trigger when a new offer is created.
OFFER_UPDATED
Will trigger when an update is made to an offer.
OFFER_REMOVED
Will trigger when an offer is no longer available for purchase.
OFFER_ADDED
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. This event provides the most comprehensive availability information.
Collections
COLLECTION_CREATED
Will trigger when a new collection is created.
COLLECTION_UPDATED
Will trigger when an update is made to a collection.
COLLECTION_REMOVED
Will trigger when a collection is no longer available.
COLLECTION_OFFERS_UPDATED
Will trigger when offers in a collection are added or removed.
Syncs
PRODUCT_SYNC_STARTED
Will trigger when the merchant's products begin syncing. Payload example here.
PRODUCT_SYNC_COMPLETED
Will trigger when the merchant's products sync is completed. Example here.
PRODUCT_SYNC_FAILED
Will trigger if the merchant's products sync fails. Example here.
COLLECTION_SYNC_STARTED
Will trigger when the merchant's collections begin syncing.
COLLECTION_SYNC_COMPLETED
Will trigger when the merchant's collections sync is completed.
COLLECTION_SYNC_FAILED
Will trigger if the merchant's collections sync fails.
Webhook Headers
Violet provides headers to all webhook calls that help understanding and filtering the events by your service.
Default headers
X-Violet-Hmac
Signed hmac with your app secret for security validation.
X-Violet-Topic
Event topic as defined in Webhook Events section.
X-Violet-Event-Id
Unique event id. This allows your service to process an event just once in case of duplicated delivery.
X-Violet-Entity-Id
Related entity id. For example, an offer webhook will have the Violet Offer Id here.
X-Violet-Entity-Length
Entity's length (bytes) in the event body.
X-Violet-Webhook-Id
Triggered webhook id.
Additional headers
Certain events may have additional headers specific to that webhook type. Current additional headers:
X-Violet-Order-Id
Related order id.
X-Violet-Bag-Id
Related bag id.
X-Violet-Event-Id-Source
Event id that was used to resend a webhook.
X-Violet-Reason
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.
Last updated
Was this helpful?