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:

1. Receive webhook event.
2. Add request to a queue (Database, Kafka, SQS, etc).
3. Respond with a 2XX response.

In a separate thread:

1. Get request from queue.
2. Validate hmac.
3. 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:

1. 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.
2. 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.
3. 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
• Offer Updated
• Offer Removed

​

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.

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

​

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

{
  "status": "IN_PROGRESS",
  "merchant_id": 10069
}

​

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:

1. APP_INSTALLED_ON_PLATFORM
2. APP_UNINSTALLED_FROM_PLATFORM
3. MERCHANT_PLATFORM_PLAN_INACTIVE
4. MERCHANT_CREDENTIAL_INVALID
5. MERCHANT_PLATFORM_SCOPES_INVALID

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

Merchant Needs Attention and Merchant Complete webhooks use the following format. Possible statuses are COMPLETE, INCOMPLETE, NEEDS_ATTENTION, NOT_APPLICABLE, and ERROR.

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