Webhook events

Reference for every event the Webhook destination delivers. Setup, signature verification and retries are covered there. This page is generated from the schemas we validate payloads against, so it always matches what we send.

Request body

Every request has the same envelope. Only data differs by event type.

Field	Type	Description
`id`	`string`	Event id; same as the webhook-id header and stable across retries.
`type`	`string`	The event type, e.g. order_placed.
`version`	`1`	Payload version. Changes only on a breaking change.
`timestamp`	`string`	ISO-8601 time the action happened.
`data`	object	Event-specific payload; see each event type below.

All amounts are integers in minor units, so 2500 in USD is $25.00. Timestamps are ISO-8601 in UTC.

Versioning

The current payload version is 1. It changes only for a breaking change: a field removed or renamed, or a field's type or meaning changed. Adding a field or a new event type is not breaking and keeps the version, so ignore fields and event types you don't recognize. When a new version ships, your endpoint keeps receiving the version it has until you switch, and the old version stays supported for a deprecation period announced in advance.

Event types

Type	Fires when	Sent
`order_placed`	Payment for an order was captured.	Always (our backend emits it)
`order_fulfilled`	An order was marked fulfilled.	Always (our backend emits it)
`order_refunded`	An order was refunded.	Always (our backend emits it)
`order_cancelled`	An order was cancelled.	Always (our backend emits it)
`customer_registered`	A shopper created an account.	Always (our backend emits it)
`customer_identified`	An existing shopper signed in. A storefront can also send it with `trackEvent` to identify a visitor.	Always (our backend emits it)
`newsletter_subscribed`	A shopper submitted a newsletter subscribe form.	Always (our backend emits it)
`product_viewed`	A shopper viewed a product.	Only when your storefront sends it with `trackEvent`
`product_added_to_cart`	A shopper added a product to the cart.	Only when your storefront sends it with `trackEvent`
`checkout_started`	A shopper started checkout.	Only when your storefront sends it with `trackEvent`
`custom`	A store-specific event, e.g. a quiz completed.	Only when your storefront sends it with `trackEvent`

The "Send test event" button sends type nanosite_test_event, whose data has only a note.

`order_placed`

Payment for an order was captured. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`order`	Order	An order as it was when the event fired.

Example request body:

{
  "id": "mevt_01JEXAMPLE0001",
  "type": "order_placed",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": null,
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": null
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "order": {
      "id": "order_01JEXAMPLE",
      "status": "paid",
      "email": "[email protected]",
      "currencyCode": "USD",
      "subtotal": 5000,
      "discountCode": "WELCOME10",
      "discountAmount": 500,
      "shippingAmount": 600,
      "taxAmount": 0,
      "total": 5100,
      "shippingAddress": {
        "name": "Sam Shopper",
        "line1": "1 Main St",
        "line2": null,
        "city": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "US",
        "phone": "+15555550100"
      },
      "items": [
        {
          "productId": "prod_01JEXAMPLE",
          "variantId": "var_01JEXAMPLE",
          "title": "Organic Cotton Tee / M",
          "quantity": 2,
          "unitAmount": 2500
        }
      ],
      "metadata": {
        "giftNote": "Happy birthday!"
      },
      "createdAt": "2026-09-30T11:58:00.000Z"
    }
  }
}

`order_fulfilled`

An order was marked fulfilled. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`order`	Order	An order as it was when the event fired.

Example request body:

{
  "id": "mevt_01JEXAMPLE0002",
  "type": "order_fulfilled",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": null,
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": null
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "order": {
      "id": "order_01JEXAMPLE",
      "status": "fulfilled",
      "email": "[email protected]",
      "currencyCode": "USD",
      "subtotal": 5000,
      "discountCode": "WELCOME10",
      "discountAmount": 500,
      "shippingAmount": 600,
      "taxAmount": 0,
      "total": 5100,
      "shippingAddress": {
        "name": "Sam Shopper",
        "line1": "1 Main St",
        "line2": null,
        "city": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "US",
        "phone": "+15555550100"
      },
      "items": [
        {
          "productId": "prod_01JEXAMPLE",
          "variantId": "var_01JEXAMPLE",
          "title": "Organic Cotton Tee / M",
          "quantity": 2,
          "unitAmount": 2500
        }
      ],
      "metadata": {
        "giftNote": "Happy birthday!"
      },
      "createdAt": "2026-09-30T11:58:00.000Z"
    }
  }
}

`order_refunded`

An order was refunded. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`order`	Order	An order as it was when the event fired.

Example request body:

{
  "id": "mevt_01JEXAMPLE0003",
  "type": "order_refunded",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": null,
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": null
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "order": {
      "id": "order_01JEXAMPLE",
      "status": "refunded",
      "email": "[email protected]",
      "currencyCode": "USD",
      "subtotal": 5000,
      "discountCode": "WELCOME10",
      "discountAmount": 500,
      "shippingAmount": 600,
      "taxAmount": 0,
      "total": 5100,
      "shippingAddress": {
        "name": "Sam Shopper",
        "line1": "1 Main St",
        "line2": null,
        "city": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "US",
        "phone": "+15555550100"
      },
      "items": [
        {
          "productId": "prod_01JEXAMPLE",
          "variantId": "var_01JEXAMPLE",
          "title": "Organic Cotton Tee / M",
          "quantity": 2,
          "unitAmount": 2500
        }
      ],
      "metadata": {
        "giftNote": "Happy birthday!"
      },
      "createdAt": "2026-09-30T11:58:00.000Z"
    }
  }
}

`order_cancelled`

An order was cancelled. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`order`	Order	An order as it was when the event fired.

Example request body:

{
  "id": "mevt_01JEXAMPLE0004",
  "type": "order_cancelled",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": null,
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": null
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "order": {
      "id": "order_01JEXAMPLE",
      "status": "cancelled",
      "email": "[email protected]",
      "currencyCode": "USD",
      "subtotal": 5000,
      "discountCode": "WELCOME10",
      "discountAmount": 500,
      "shippingAmount": 600,
      "taxAmount": 0,
      "total": 5100,
      "shippingAddress": {
        "name": "Sam Shopper",
        "line1": "1 Main St",
        "line2": null,
        "city": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "US",
        "phone": "+15555550100"
      },
      "items": [
        {
          "productId": "prod_01JEXAMPLE",
          "variantId": "var_01JEXAMPLE",
          "title": "Organic Cotton Tee / M",
          "quantity": 2,
          "unitAmount": 2500
        }
      ],
      "metadata": {
        "giftNote": "Happy birthday!"
      },
      "createdAt": "2026-09-30T11:58:00.000Z"
    }
  }
}

`customer_registered`

A shopper created an account. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`method`	`"password"`, `"google"`, `"magic_link"`, `"otp"`	How the account was created.

Example request body:

{
  "id": "mevt_01JEXAMPLE0005",
  "type": "customer_registered",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "signup"
    },
    "method": "google"
  }
}

`customer_identified`

An existing shopper signed in. A storefront can also send it with trackEvent to identify a visitor. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.

Example request body:

{
  "id": "mevt_01JEXAMPLE0006",
  "type": "customer_identified",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    }
  }
}

`newsletter_subscribed`

A shopper submitted a newsletter subscribe form. Sent: Always (our backend emits it).

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`list`	`string` or `null`	The list they joined, if named.

Example request body:

{
  "id": "mevt_01JEXAMPLE0007",
  "type": "newsletter_subscribed",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": null,
      "email": "[email protected]",
      "phone": null,
      "name": null
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "subscribe-form"
    },
    "list": "newsletter"
  }
}

`product_viewed`

A shopper viewed a product. Sent: Only when your storefront sends it with trackEvent.

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`line`	Line	A product line on a browsing or cart event.

Example request body:

{
  "id": "mevt_01JEXAMPLE0008",
  "type": "product_viewed",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "line": {
      "productId": "prod_01JEXAMPLE",
      "variantId": "var_01JEXAMPLE",
      "title": "Organic Cotton Tee / M",
      "image": "https://cdn.example.com/tee.jpg",
      "quantity": 1,
      "unitAmount": 2500,
      "currencyCode": "USD"
    }
  }
}

`product_added_to_cart`

A shopper added a product to the cart. Sent: Only when your storefront sends it with trackEvent.

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`line`	Line	A product line on a browsing or cart event.

Example request body:

{
  "id": "mevt_01JEXAMPLE0009",
  "type": "product_added_to_cart",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "line": {
      "productId": "prod_01JEXAMPLE",
      "variantId": "var_01JEXAMPLE",
      "title": "Organic Cotton Tee / M",
      "image": "https://cdn.example.com/tee.jpg",
      "quantity": 2,
      "unitAmount": 2500,
      "currencyCode": "USD"
    }
  }
}

`checkout_started`

A shopper started checkout. Sent: Only when your storefront sends it with trackEvent.

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`checkout`	Checkout	The cart when checkout started.

Example request body:

{
  "id": "mevt_01JEXAMPLE0010",
  "type": "checkout_started",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "checkout": {
      "cartId": "cart_01JEXAMPLE",
      "currencyCode": "USD",
      "value": 5000,
      "items": [
        {
          "productId": "prod_01JEXAMPLE",
          "variantId": "var_01JEXAMPLE",
          "title": "Organic Cotton Tee / M",
          "image": "https://cdn.example.com/tee.jpg",
          "quantity": 2,
          "unitAmount": 2500,
          "currencyCode": "USD"
        }
      ]
    }
  }
}

`custom`

A store-specific event, e.g. a quiz completed. Sent: Only when your storefront sends it with trackEvent.

data fields:

Field	Type	Description
`profile`	Profile	Who the event is about. Any field can be `null`.
`consent`	Consent	Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.
`name`	`string`	The custom event name, e.g. "quiz_completed".
`props`	object	Flat properties sent with the event.

Example request body:

{
  "id": "mevt_01JEXAMPLE0011",
  "type": "custom",
  "version": 1,
  "timestamp": "2026-09-30T12:00:00.000Z",
  "data": {
    "profile": {
      "customerId": "cus_01JEXAMPLE",
      "email": "[email protected]",
      "phone": "+15555550100",
      "name": "Sam Shopper"
    },
    "consent": {
      "marketing": true,
      "analytics": true,
      "region": "US",
      "source": "checkout"
    },
    "name": "quiz_completed",
    "props": {
      "quiz": "skin-type",
      "result": "dry"
    }
  }
}

Profile object

Who the event is about. Any field can be null.

Field	Type	Description
`customerId`	`string` or `null`	The shopper's customer id, when they have an account.
`email`	`string` or `null`	The shopper's email.
`phone`	`string` or `null`	The shopper's phone, from the shipping address when given.
`name`	`string` or `null`	The shopper's name.

Consent the shopper gave with the action. Webhook delivery is not gated on it, so check it before using the data for marketing.

Field	Type	Description
`marketing`	`boolean`	The shopper agreed to marketing messages.
`analytics`	`boolean`	The shopper agreed to analytics tracking.
`region`	`string` or `null`	Region the consent applies to, when known.
`source`	`string` or `null`	Where consent was captured, e.g. "checkout" or "signup".

Order object

An order as it was when the event fired.

Field	Type	Description
`id`	`string`	Order id.
`status`	`"pending"`, `"paid"`, `"fulfilled"`, `"cancelled"`, `"refunded"`	Order status when the event fired.
`email`	`string`	Email given at checkout.
`currencyCode`	`string`	ISO 4217 currency code, e.g. USD.
`subtotal`	`integer`	Sum of the lines before discounts, shipping and tax, in minor units (2500 = 25.00).
`discountCode`	`string` or `null`	Discount code applied, if any.
`discountAmount`	`integer`	Total discount, in minor units (2500 = 25.00).
`shippingAmount`	`integer`	Shipping charge, in minor units (2500 = 25.00).
`taxAmount`	`integer`	Tax, in minor units (2500 = 25.00).
`total`	`integer`	Amount charged, in minor units (2500 = 25.00).
`shippingAddress`	Address or `null`	Where the order ships, if an address was given.
`items`	array of OrderItem	The order lines.
`metadata`	object	Custom order fields set at checkout, e.g. a gift note.
`createdAt`	`string`	ISO-8601 time the order was created.

OrderItem object

One line of an order.

Field	Type	Description
`productId`	`string`	Product id.
`variantId`	`string`	Variant id.
`title`	`string`	Product title at the time of purchase, including the variant.
`quantity`	`integer`	Units ordered.
`unitAmount`	`integer`	Price of one unit, in minor units (2500 = 25.00).

Address object

A shipping address.

Field	Type	Description
`name`	`string`	Recipient name.
`line1`	`string`	Street address.
`line2`	`string` or `null`	Apartment, suite or unit.
`city`	`string`	City.
`region`	`string` or `null`	State, province or region.
`postalCode`	`string`	Postal or ZIP code.
`country`	`string`	Country, as entered at checkout.
`phone`	`string` or `null`	Contact phone.

Line object

A product line on a browsing or cart event.

Field	Type	Description
`productId`	`string` or `null`	Product id.
`variantId`	`string` or `null`	Variant id.
`title`	`string`	Product title, including the variant.
`image`	`string` or `null`	Product image URL.
`quantity`	`integer`	Units.
`unitAmount`	`integer`	Price of one unit, in minor units (2500 = 25.00).
`currencyCode`	`string`	ISO 4217 currency code.

Checkout object

The cart when checkout started.

Field	Type	Description
`cartId`	`string`	Cart id.
`currencyCode`	`string`	ISO 4217 currency code.
`value`	`integer`	Cart subtotal when checkout started, in minor units (2500 = 25.00).
`items`	array of Line	The cart lines.

Webhook events

Request body

Versioning

Event types

order_placed

order_fulfilled

order_refunded

order_cancelled

customer_registered

customer_identified

newsletter_subscribed

product_viewed

product_added_to_cart

checkout_started

custom

Profile object

Consent object

Order object

OrderItem object

Address object

Line object

Checkout object

`order_placed`

`order_fulfilled`

`order_refunded`

`order_cancelled`

`customer_registered`

`customer_identified`

`newsletter_subscribed`

`product_viewed`

`product_added_to_cart`

`checkout_started`

`custom`