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:
Receive webhook event.
Add request to a queue (Database, Kafka, SQS, etc).
Respond with a 2XX response.
In a separate thread:
Get request from queue.
Validate hmac.
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:
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
.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.
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
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.
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
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.
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
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:
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.
Last updated
Was this helpful?