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:

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 submiting 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.

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.

OFFER_CREATED

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.

PRODUCT_SYNC_STARTED

Will trigger when the merchant’s products begin syncing. Payload example here.

PRODUCT_SYNC_COMPLETED

Will trigger when the merchant’s product sync is completed. Example here.

PRODUCT_SYNC_FAILED

Will trigger if the merchant’s product sync fails. Example here.

MERCHANT_NEEDS_ATTENTION

Will trigger if the merchant has any INCOMPLETE or NEEDS_ATTENTION items during the connection health check. Example here.

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 conference.

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.

X-Violet-Entity-Length

Entity’s length (bytes) in body.

X-Violet-Webhook-Id

Triggered webhook id.

Aditional headers

Certain events may have aditional headers to support the webhook. Current aditional headers:

X-Violet-Order-Id

Related order id.

X-Violet-Bag-Id

Related entity id.

X-Violet-Reason

Aditional context to what trigger 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 help identifying the events per webhook.

Please refer to Managing Webhook Headers.

Handling 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

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.

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.

JSON

{
  "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"
}

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, being APP_INSTALLED_ON_PLATFORM, APP_UNINSTALLED_FROM_PLATFORM, MERCHANT_PLATFORM_PLAN_INACTIVE, MERCHANT_CREDENTIAL_INVALID and MERCHANT_PLATFORM_SCOPES_INVALID the current possibilities.

JSON

{
  "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 Webhooks

Merchant Needs Attention webhooks use the following format. Possible statuses are COMPLETE, INCOMPLETE, NEEDS_ATTENTION, NOT_APPLICABLE, and ERROR; the status(es) that caused the webhook to fire will be in INCOMPLETE or NEEDS_ATTENTION status.

JSON

{
  "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"
  }
}

Big Webhook Requests

Violet webhook request bodies always contain the related entity data disregarding its size. In a scenario that the client cannot consume the request entirely, it’s possible to ignore the body and request it in a later moment.

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.

Get Started

Concepts

Relay

Guides

Product Info

Overview

Webhook Events

Webhook Headers

Default headers

Aditional headers

Custom headers

Handling Webhooks

Product Sync Webhooks

Merchant Enabled / Disabled Webhooks

Merchant Needs Attention Webhooks

Big Webhook Requests

Get Started

Concepts

Relay

Guides

Product Info

​Overview

​Webhook Events

​Webhook Headers

​Default headers

​Aditional headers

​Custom headers

​Handling Webhooks

​Order Related Webhooks

​Offer Related Webhooks

​Product Sync Webhooks

​Merchant Related Webhooks

​Merchant Enabled / Disabled Webhooks

​Merchant Needs Attention Webhooks

​Big Webhook Requests

Overview

Webhook Events

Webhook Headers

Default headers

Aditional headers

Custom headers

Handling Webhooks

Order Related Webhooks

Offer Related Webhooks

Product Sync Webhooks

Merchant Related Webhooks

Merchant Enabled / Disabled Webhooks

Merchant Needs Attention Webhooks

Big Webhook Requests