Event Reference

Complete reference for all 13 Whatalo webhook events — order, product, customer, inventory, and plugin lifecycle events.

Whatalo supports 13 webhook events across 5 categories. Declare only the events your plugin actually handles in your whatalo.app.ts manifest.

Subscribing to Events

// whatalo.app.ts
webhooks: [
  { event: "order.created", description: "Track new orders for fulfilment" },
  { event: "product.updated" },
  { event: "app.installed", description: "Welcome new merchants" },
  { event: "app.uninstalled", description: "Clean up merchant data" },
],

The description field is optional but recommended — it appears on the merchant's install permission screen.

Order Events

Event	Trigger
`order.created`	A new order is placed in the store
`order.updated`	An order's details are modified (items, address, notes)
`order.status_changed`	An order's status changes (e.g., `pending` → `confirmed`)
`order.cancelled`	An order is cancelled by the merchant or customer

order.created

{
  "id": "evt_01HX4KQMZ7B9XVNR2T6WQFG3P",
  "event": "order.created",
  "store": "my-store",
  "timestamp": "2024-03-01T14:30:00Z",
  "data": {
    "id": "order_789",
    "status": "pending",
    "total": 149.99,
    "currency": "DOP",
    "customer": {
      "name": "Ana García",
      "email": "[email protected]",
      "phone": "+1-809-555-0123"
    },
    "items": [
      { "productId": "472819365047", "quantity": 2, "price": 74.99 }
    ]
  }
}

order.status_changed

{
  "event": "order.status_changed",
  "data": {
    "id": "order_789",
    "previousStatus": "pending",
    "status": "confirmed"
  }
}

Product Events

Event	Trigger
`product.created`	A new product is added to the catalog
`product.updated`	A product's details are modified (name, price, images)
`product.deleted`	A product is permanently removed

product.updated

{
  "event": "product.updated",
  "data": {
    "id": "472819365047",
    "name": "Premium T-Shirt (Updated)",
    "price": 39.99,
    "status": "active"
  }
}

Customer Events

Event	Trigger
`customer.created`	A new customer registers on the storefront
`customer.updated`	A customer's profile information is modified

customer.created

{
  "event": "customer.created",
  "data": {
    "id": "365047281936",
    "name": "Ana García",
    "email": "[email protected]",
    "phone": "+1-809-555-0123"
  }
}

Inventory Events

Event	Trigger
`inventory.low`	Inventory falls below the configured low-stock threshold
`inventory.adjusted`	A product's inventory quantity is manually adjusted

inventory.low

{
  "event": "inventory.low",
  "data": {
    "productId": "472819365047",
    "productName": "Premium T-Shirt",
    "quantity": 3,
    "threshold": 5
  }
}

inventory.adjusted

{
  "event": "inventory.adjusted",
  "data": {
    "productId": "472819365047",
    "previousQuantity": 50,
    "newQuantity": 45,
    "delta": -5,
    "reason": "Manual adjustment"
  }
}

Plugin Lifecycle Events

These events fire when a merchant installs or uninstalls your plugin. Use them to provision or clean up merchant-specific resources.

Event	Trigger
`app.installed`	A merchant completes the installation of your plugin
`app.uninstalled`	A merchant uninstalls your plugin

app.installed

{
  "event": "app.installed",
  "store": "merchant-store-slug",
  "data": {
    "storeId": "store_abc",
    "installedAt": "2024-03-01T10:00:00Z"
  }
}

app.uninstalled

{
  "event": "app.uninstalled",
  "store": "merchant-store-slug",
  "data": {
    "storeId": "store_abc",
    "uninstalledAt": "2024-06-15T08:22:00Z"
  }
}

When you receive app.uninstalled, delete all data you have stored for that merchant. Retaining merchant data after uninstallation violates the plugin publishing guidelines.

CLI Test Support

The whatalo webhook trigger CLI command supports a subset of 9 events for local development testing:

CLI Constant	Webhook Event
`ORDER_CREATED`	`order.created`
`ORDER_UPDATED`	`order.updated`
`ORDER_CANCELLED`	`order.cancelled`
`PRODUCT_CREATED`	`product.created`
`PRODUCT_UPDATED`	`product.updated`
`PRODUCT_DELETED`	`product.deleted`
`CUSTOMER_CREATED`	`customer.created`
`CUSTOMER_UPDATED`	`customer.updated`
`CHECKOUT_COMPLETED`	(checkout flow completion)

# Trigger a test order.created event against your dev store
whatalo webhook trigger ORDER_CREATED --store my-dev-store

inventory.low, inventory.adjusted, app.installed, app.uninstalled, and order.status_changed are not available via the CLI trigger command. Test these by simulating the action in a development store through the admin dashboard.

On this page