How to Use Webhook Documentation

Webhook Payload Structure

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.

All webhook payloads follow this structure:

{
 "id": "webhook-event-uuid",
 "type": "EVENT_TYPE",
 "data": {},
 "created": "2024-01-15T10:30:00.000Z"
}

Payload Fields

id (string): Unique identifier for this webhook event
type (string): The event type (e.g., PRODUCTCREATED, \`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)	Unique product identifier
name	string	Product name
created	string (ISO 8601)	Date the product was created
modified	string (ISO 8601)	Date the product was last modified
organization	string (UUID)	Organization identifier
venue	string (UUID)	Venue identifier
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 quantity a customer can purchase
quantityTotal	number	Total quantity available
description	string	Product description
size	string	Product size (e.g., small, medium)
weight	number	Product weight value
weightUnit	string	Unit of weight: `GRAMS`, `MILLIGRAMS`, `OUNCES`, `EACH`, `UNKNOWN`
weightFormatted	string	Formatted weight (example: `3.5g`)
discountValue	number	Discount value (percent or flat amount)
discountType	string	Discount type: `PERCENT` or `FLAT`
discountAmount	number	Calculated discount amount in dollars
discounts	array	List of discounts applied to the product
tiers	array \| null	Tiered pricing or weight tiers
variants	array \| null	Product variants

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: ORDEROUTFOR_DELIVERY

ORDER\_READY\_FOR\_PICKUP

Triggered when an order is ready for customer pickup.

Event Type: ORDERREADYFOR_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 (UUID)	Unique order identifier
created	string (ISO 8601)	When the order was created
modified	string (ISO 8601)	When the order was last modified
organization	string (UUID)	Organization identifier
venue	string (UUID)	Venue identifier
status	string	Order status: `PENDING`, `CONFIRMED`, `CLOSED`, `CANCELLED`
paymentStatus	string	Payment status: `NONE`, `PAID`, `CANCELLED`
paymentType	string	Payment type: `CASH`, `DEBIT`, `OTHER`, `AEROPAY`, `STRIPE`
subtotal	number	Order subtotal after discounts
total	number	Final order total
discountTotal	number	Total discount amount
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
price	number	Item price
quantity	number	Quantity ordered
weightUnit	string \| null	Weight unit: `GRAMS`, `MILLIGRAMS`, `OUNCES`, `EACH`, `UNKNOWN`
discountType	string \| null	Discount type: `PERCENT` or `FLAT`

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
ORDER_CANCELLED – Order cancelled
ORDER_CLOSED – Order closed/completed
ORDEROUTFOR_DELIVERY – Order marked as out for delivery
ORDERREADYFOR_PICKUP – Order ready for customer pickup
ORDER_DELIVERED – Order marked as delivered
ORDER_SHIPPED – Order shipped

Need Help?

If you need assistance, reach out to AIQ Support anytime via chat widget within your AIQ Dashboard.

Create Webhooks