Ecommerce
...
Webhooks
Webhook Documentation
17 min
overview webhooks allow you to receive real time notifications when events occur in your aiq ecommerce account when a configured event is triggered, aiq ecom sends an http post request to your specified webhook url with a json payload containing the event data webhook payload structure all webhook payloads follow this structure { "id" "webhook event uuid", "type" "event type", "data" { // event specific data (product or order object) }, "created" "2024 01 15t10 30 00 000z" } payload fields id (string) unique identifier for this webhook event type (string) the event type (e g , product created , `order created) data (object) the event data contains either a product or order object depending on the event type created (string) iso 8601 timestamp when the webhook event was created product events product created triggered when a new product is created in your venue event type product created product updated triggered when an existing product is updated event type product updated product deleted triggered when a product is deleted event type product deleted product example payload { "id" "550e8400 e29b 41d4 a716 446655440002", "type" "product updated", "data" { "id" "123e4567 e89b 12d3 a456 426614174000", "name" "og kush", "created" "2024 01 15t10 30 00 000z", "modified" "2024 01 15t16 45 00 000z", "organization" "org 123e4567 e89b 12d3 a456 426614174000", "venue" "venue 123e4567 e89b 12d3 a456 426614174000", "type" "flower", "price" 45 0, "pricewithdiscounts" 40 5, "pricegross" 45 0, "pricenet" 40 5, "pricetype" "regular", "quantity" 0, "quantitythreshold" 10, "purchasemax" 5, "quantitytotal" 0, "description" "a classic indica dominant hybrid with earthy, pine flavors", "size" "3 5g", "weight" 3 5, "weightunit" "grams", "weightformatted" "3 5g", "discountvalue" 0 1, "discounttype" "percent", "discountamount" 4 5, "discounts" \[], "tiers" null, "variants" null }, "created" "2024 01 15t16 45 00 000z" } product data fields field type description id string uuid name string product name created string (iso 8601) when the product was created modified string (iso 8601) when the product was last modified organization string organization uuid venue string venue uuid type string product category price number base price of the product pricewithdiscounts number price after discounts are applied pricegross number gross price pricenet number net price pricetype string pricing type regular , weight tier , or price tier quantity number current inventory quantity quantitythreshold number low stock threshold purchasemax number maximum purchase quantity per customer quantitytotal number total quantity available description string product description size string product size (small, etc) weight number product weight as a number weightunit string weight unit grams , milligrams , ounces , each or unknown weightformatted string formatted weight string (3 5g) discountvalue number discount value (decimal for percent , dollar for flat discounttype string discount type percent or flat discountamount number calculated discount amount in dollars discounts array array of discount objects applied to the product tiers array | null price/weight tiers for tiered pricing products variants array | null product variants if applicable order events order created triggered when a new order is created event type order created order confirmed triggered when an order is confirmed event type order confirmed order updated triggered when an order is updated (status change, item modification, etc ) event type order updated order cancelled triggered when an order is cancelled event type order cancelled order closed triggered when an order is closed/completed event type order closed order out for delivery triggered when an order is marked as out for delivery event type order out for delivery order ready for pickup triggered when an order is ready for customer pickup event type order ready for pickup order delivered triggered when an order is marked as delivered event type order delivered order shipped triggered when an order is shipped event type order shipped order example payload { "id" "550e8400 e29b 41d4 a716 446655440018", "type" "order shipped", "data" { "id" "order 123e4567 e89b 12d3 a456 426614174000", "created" "2024 01 15t10 30 00 000z", "modified" "2024 01 15t16 00 00 000z", "organization" "org 123e4567 e89b 12d3 a456 426614174000", "venue" "venue 123e4567 e89b 12d3 a456 426614174000", "status" "closed", "statuschangedon" "2024 01 15t16 00 00 000z", "substatus" "shipped", "substatuschangedon" "2024 01 15t16 00 00 000z", "paymentstatus" "paid", "paymentachstatus" null, "paymenttype" "debit", "subtotal" 90 0, "subtotalwithoutdiscounts" 100 0, "tax" 8 1, "taxes" \[ { "name" "sales tax", "amount" 0 09, "value" 8 1 } ], "fees" \[ { "name" "shipping fee", "amount" 10 0, "type" "flat", "value" 10 0 } ], "feetotal" 10 0, "feetotalbeforeoraftertax" null, "feetotalontotalaftertax" null, "total" 108 1, "discounts" \[ { "name" "10% off first order", "value" 0 1, "type" "percent", "amount" 10 0 } ], "totaltax" 8 1, "discounttotal" 10 0, "productoffers" \[], "items" \[ { "id" "item 123e4567 e89b 12d3 a456 426614174001", "product" "123e4567 e89b 12d3 a456 426614174000", "name" "og kush", "slug" "og kush", "image" "https //example com/image jpg", "sku" "ogk 001", "brand" "premium brand", "cannabiscompliancetype" "flower", "productcategory" "cat 123e4567 e89b 12d3 a456 426614174000", "productcategoryname" "flower", "subtype" null, "description" "a classic indica dominant hybrid", "size" "3 5g", "price" 45 0, "quantity" 2, "purchaseweight" 7 0, "weight" 3 5, "weightunit" "grams", "weightformatted" "3 5g", "weighttierweight" null, "discountvalue" null, "discounttype" null, "discountamount" null, "discounttotal" null, "modifiergroups" null } ] }, "created" "2024 01 15t16 00 00 000z" } order data fields field type description id string unique order identifier (uuid) created string (iso 8601) when the order was created modified string (iso 8601) when the order was last modified organization string organization uuid venue string venue uuid status string order status pending , confirmed , checked in , ready for pickup , out for delivery , closed , cancelled statuschangedon string (iso 8601) when the order status was last changed substatus string|null custom sub status for the order substatuschangedon string (iso 8601)|null when the sub status was last changed paymentstatus string payment status none , pending user action , paid , cancelled paymentachstatus string|null ach payment status authed , captured paymenttype string payment type cash , debit , other , can pay , kind tap , aeropay , square , stripe subtotal number order subtotal after discounts subtotalwithoutdiscounts number order subtotal before discounts tax number total tax amount taxes array array of tax objects with name, amount (percentage), and value fees array array of fee objects with name, amount, type, and value feetotal number sum of all fees feetotalbeforeoraftertax number|null fee calculation timing feetotalontotalaftertax number|null fee calculation on total after tax total number final order total discounts array array of discount objects applied to the order totaltax number total tax amount (same as tax) discounttotal number total discount amount productoffers array array of product offers applied items array array of order item objects order item fields field type description id string unique item identifier product string product uuid name string product name slug string url friendly product name image string|null product image url sku string|null product sku brand string|null product brand cannabiscompliancetype string|null cannabis compliance type productcategory string|null product category uuid productcategoryname string|null product category name subtype string|null product sub type description string|null product description size string|null product size price number item price quantity number quantity ordered purchaseweight number|null weight purchased weight number|null product weight weightunit string|null weight unit grams, milligrams, ounces, each, unknown weightformatted string|null formatted weight string weighttierweight number|null weight tier weight if applicable discountvalue number|null discount value for this item discounttype string|null discount type percent or flat discountamount number|null discount amount for this item discounttotal number|null total discount for this item modifiergroups array|null array of modifier groups selected for this item webhook best practices idempotency use the id field to ensure you donβt process the same webhook event multiple times response time respond to webhook requests within 5 seconds aiq ecom will retry failed webhooks up to 3 times with exponential backoff (30s, 1m, 2m) status codes return a 2xx status code to indicate successful processing any 4xx or 5xx status will trigger a retry error handling log all webhook events for debugging and audit purposes testing test your webhook endpoint with sample payloads before going live event type reference product events product created β new product created product updated β existing product updated product deleted β product deleted order events order created β new order created order confirmed β order confirmed order updated β order updated (status change, item modification, etc ) order cancelled β order cancelled order closed β order closed/completed order out for delivery β order marked as out for delivery order ready for pickup β order ready for customer pickup order delivered β order marked as delivered order shipped β order shipped