Event Reference

Whatalo currently delivers 10 public webhook events. 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: "order.updated", description: "Sync order changes" },
  { event: "product.updated", description: "Sync catalog changes" },
  { event: "checkout.completed", description: "React to completed checkouts" },
],

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

Event Headers

The event name is delivered in X-Webhook-Event. The JSON body contains event-specific data and does not include an event field.

For order, customer, and product events, event_id is the public identifier of the affected entity and matches the nested order.id, customer.id, or product.id. Use the delivery header X-Webhook-Id for per-delivery idempotency.

Order Events

Event	Trigger
`order.created`	A new order is placed
`order.updated`	An order's details, status, or payment status changes
`order.cancelled`	An order is cancelled
`order.completed`	An order is completed

Example: `order.created`

{
  "event_id": "ord_abc123",
  "occurred_at": "2026-03-01T14:30:00.000Z",
  "order": {
    "id": "ord_abc123",
    "status": "pending",
    "total": 1500.5,
    "currency": "DOP",
    "shipping_address": {
      "address": "Calle 1 #2",
      "city": "Santo Domingo",
      "province": "Distrito Nacional",
      "country": "República Dominicana",
      "postal_code": "10101"
    },
    "items": [
      {
        "product_id": "prd_abc123",
        "product_name": "Starter Kit",
        "variant_name": "Color: Rojo",
        "quantity": 2,
        "unit_price": 750.25,
        "total_price": 1500.5
      }
    ]
  },
  "customer": {
    "id": "cus_abc123",
    "name": "Ana Perez"
  },
  "store": {
    "id": "sto_abc123",
    "name": "My Store",
    "timezone": "America/Santo_Domingo"
  }
}

Product Events

Event	Trigger
`product.created`	A product is created
`product.updated`	A product's details change
`product.deleted`	A product is deleted

Example: `product.updated`

{
  "event_id": "prd_abc123",
  "occurred_at": "2026-03-01T14:30:00.000Z",
  "product": {
    "id": "prd_abc123",
    "name": "Starter Kit",
    "price": 1500.5
  },
  "store": {
    "id": "sto_abc123",
    "timezone": "America/Santo_Domingo"
  }
}

Customer Events

Event	Trigger
`customer.created`	A customer is created
`customer.updated`	A customer's profile changes

Example: `customer.created`

{
  "event_id": "cus_abc123",
  "occurred_at": "2026-03-01T14:30:00.000Z",
  "customer": {
    "id": "cus_abc123",
    "name": "Ana Perez",
    "phone": "8090000000"
  },
  "store": {
    "id": "sto_abc123",
    "timezone": "America/Santo_Domingo"
  }
}

Checkout Events

Event	Trigger
`checkout.completed`	A checkout flow completes
`checkout.abandoned`	A checkout draft is marked abandoned after inactivity

Checkout payloads include the fields available for that checkout event. Treat unknown fields as additive and ignore fields your plugin does not need.

For checkout.abandoned, event_id matches the nested checkout.id, the customer object has no id (the draft is pre-customer, contact fields only), and checkout.recovery_url links back to the shopper's cart.

CLI Test Support

The whatalo webhook trigger CLI command supports local testing for these public events:

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.completed`

whatalo webhook trigger ORDER_CREATED --store my-dev-store

On this page