Webhooks

If you are using our Shopify App, this section is irrelevant and you should follow Installing our Shopify App instead. See Purple Dot Overview for the comparison of our Shopify App vs. Platform integrations.

Overview

This reference documents available webhook subscriptions.

Webhooks allow you to stay in sync with Purple Dot store data or perform an action after a specific event occurs in a store.

Webhooks are a performant alternative to continuously polling for changes to a store's data.

You can configure webhook subscriptions on the Integration settings page of the Merchant Portal.

Note: Webhooks use the HTTP method POST to deliver requests to the provided webhook URL.

Webhooks

Product Availability Changed

This webhook is triggered whenever

• a new waitlist is created, or

• stock levels on any existing waitlist are updated, or

• shoppers make, change or cancel pre orders for a product on a live waitlist, or

• a waitlist is paused

Expected latency is a few seconds from when the relevant event occurs in the store. Each webhook delivery is attempted up to 3 times.

Webhook Headers

Field	Use	Example
X-PD-Timestamp	ISO formatted UTC timestamp of the event that triggered this webhook	"2022-04-23T12:18:16.340Z"
X-PD-Api-Key	Your Purple Dot store's Public API Key, as shown at the bottom of the Integration settings page in the Merchant Portal	"ceb8adfd-efc1-4927-a0d9-c14e7aa1ebac"
X-PD-Hmac-Sha256	HMAC-based encoded signature to allow optional webhook request source verification. The signature is created using the webhook body and your Purple Dot store's Shared Secret, as shown on the Integration settings page of the Merchant Portal	"2bxOXTiAa3OsPw0Ck/sgOLhWwwNUP+QWlUpj5k75NkA="
Content-Type	Always set to "application/json"	"application/json"

Webhook Body

When

• a new waitlist is created, or

• stock levels on any existing waitlist are updated, or

• shoppers make, change or cancel pre orders for a product on a live waitlist

{
  "data": {
    "id": "1000",
    "product_code": "Your Awesome Product",
    "available": true,
    "available_stock": 77,
    "variants": [{
      "id": "1001",
      "sku": “SKU-1”,
      "available": true,
      "available_stock": 19
    }, {
      "id": "1001",
      "sku": “SKU-2”,
      "available": true,
      "available_stock": 58
    }]
  }
}

When

• a waitlist is paused

{
  "data": {
    "id": "1000",
    "product_code": "Your Awesome Product",
    "available": false,
    "available_stock": 0,
    “timestamp”: 1648473355610,
    "variants": [{
      "id": "1001",
      "sku": “SKU-1”,
      "available": false,
      "available_stock": 0
    }, {
      "id": "1002",
      "sku": “SKU-2”,
      "available": false,
      "available_stock": 0
    }]
  }
}

Preorder Events

This webhook is triggered whenever

• a new preorder is created, or

• an existing preorder is updated or

• an existing preorder is cancelled or

• a line item in an existing preorder is cancelled

Expected latency is a few seconds from when the relevant event occurs in the store.

Webhook Headers

Field	Use	Example
Content-Type	Always set to "application/json"	"application/json"

Webhook Body

• event: Can have one of the following values:

  • pre_order.created (triggered when the preorder is placed)

  • pre_order.updated (triggered when the details of the preorder are updated)

  • pre_order.cancelled (triggered when the whole preorder or a line item in the preorder is cancelled)

• data: Contains the preorder data

  • id - The Purple Dot internal pre-order ID

  • order_number - The Purple Dot order reference number

  • currency - The presentment currency of the order

  • created_at - The time at which the order was created

  • cancelled_at - The time at which the whole order was cancelled (null if not cancelled)

  • cancel_reason - The reason for the cancellation

  • email - The customer email

  • line_items - Array of line items

    • id - The Purple Dot ID of the line item

    • quantity - The quantity of the line item

    • product_id - The Shopify ID of the line item's product

    • variant_id - The Shopify ID of the line item's variant

    • sku - The SKU of the line item's variant

    • name - The name of the line item's variant

    • taxable - Whether the line item's variant is taxable

    • total_discount - The total amount of discounts applied to the line item

    • tax_lines - The taxes applied to the line item

    • price - The total price of the item

    • cancelled_at - The time at which the line item was cancelled (null if not cancelled)

  • shipping_address

    • address1

    • address2

    • city

    • country - The English name of the country

    • country_code - The ISO3166 code of the country

    • province_code - The ISO3166 code of the second level administrative subdivision

    • postal_code

    • first_name

    • last_name

    • phone

  • shipping_lines - An array of shipping rates

    • price - The total price of the shipping rate

    • title - The user-facing name of the shipping rate

    • code - The shipping rate carrier code

    • tax_lines - The taxes applied to the shipping rate

  • subtotal_price - The total of the line items before taxes and shipping

  • total_discounts - The total discounts applied to the order

  • total_tax - The total tax on the order

  • tax_included - Whether the tax is included in listed prices or not

  • tax_lines - All the taxes applied to the order

  • total_price - The order total

  • exported_orders - Any orders that were exported to Shopify from this pre-order

    • id - The Shopify ID of the order that was exported

    • order_number - The Shopify order number

    • created_at - The time at which the order was exported

    • line_items - The pre-order line items that were exported

      • id - The Shopify ID of the line item

      • line_item_id - The Purple Dot ID of the line item