Webhook Events Reference

This page provides a complete reference for all webhook events sent by VesuvioPay, including detailed payload examples and event-specific information.

Event Structure

All webhook events follow this base structure:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H1",
  "type": "order.created",
  "created_at": "2024-01-15T10:30:00.000Z",
  "data": {
    // Event-specific data
  }
}

Base Fields:

id (string): Unique identifier for this event (use for idempotency)
type (string): Event type (e.g., cart.created, order.shipped)
created_at (string): ISO 8601 timestamp when the event occurred
data (object): Event-specific payload data

Common Data Fields (present in most events):

storeId (string): Your store identifier
customerId (string | null): Customer identifier (if available)
occurredAt (string): ISO 8601 timestamp when the action occurred
externalReference (string | null): External reference for tracking

SDK Operations Don't Trigger Webhooks

To prevent webhook loops when integrating with external platforms, SDK-triggered operations do NOT send webhooks. This includes:

Orders created via POST /api/v1/orders
Order status updates via PUT /api/v1/orders/{id}/status
Product/variant updates via SDK endpoints

Only events from direct customer interactions or internal system processes send webhooks.

Cart Events

Cart events track customer shopping activity in real-time.

cart.created

Sent when a new cart is created.

Event Type: cart.created

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H1",
  "type": "cart.created",
  "created_at": "2024-01-15T10:30:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:30:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "status": "Active",
    "items": []
  }
}

Use Cases:

Track cart creation rate
Initialize analytics tracking
Start cart abandonment timer

cart.item_added

Sent when a customer adds a product to their cart.

Event Type: cart.item_added

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H2",
  "type": "cart.item_added",
  "created_at": "2024-01-15T10:31:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:31:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "item": {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
      "externalId": "shopify_7234567890",
      "externalVariantId": "shopify_43210987654",
      "productTitle": "Premium Wireless Headphones",
      "variantTitle": "Black / Large",
      "sku": "WH-BLK-LG",
      "quantity": 1,
      "originalUnitPrice": 299.99,
      "unitPrice": 269.99,
      "originalTotalPrice": 299.99,
      "totalPrice": 269.99,
      "hasDiscount": true,
      "discountPercentage": 10.0,
      "discountAmount": 30.00,
      "addedAt": "2024-01-15T10:31:00.000Z",
      "updatedAt": null
    },
    "cartSummary": {
      "cartId": "770e8400-e29b-41d4-a716-446655440002",
      "itemCount": 1,
      "totalQuantity": 1,
      "subtotal": 269.99,
      "estimatedTax": 21.60,
      "estimatedShipping": 9.99,
      "estimatedTotal": 301.58,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:31:00.000Z",
      "status": "Active"
    }
  }
}

Use Cases:

Track product popularity and cart behavior
Trigger remarketing campaigns
Update inventory forecasting
Send real-time notifications to sales teams

cart.item_updated

Sent when a customer changes the quantity of an item in their cart.

Event Type: cart.item_updated

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H3",
  "type": "cart.item_updated",
  "created_at": "2024-01-15T10:35:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:35:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "item": {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
      "externalId": "shopify_7234567890",
      "externalVariantId": "shopify_43210987654",
      "productTitle": "Premium Wireless Headphones",
      "variantTitle": "Black / Large",
      "sku": "WH-BLK-LG",
      "quantity": 2,
      "originalUnitPrice": 299.99,
      "unitPrice": 269.99,
      "originalTotalPrice": 599.98,
      "totalPrice": 539.98,
      "hasDiscount": true,
      "discountPercentage": 10.0,
      "discountAmount": 60.00,
      "addedAt": "2024-01-15T10:31:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z"
    },
    "previousQuantity": 1,
    "cartSummary": {
      "cartId": "770e8400-e29b-41d4-a716-446655440002",
      "itemCount": 1,
      "totalQuantity": 2,
      "subtotal": 539.98,
      "estimatedTax": 43.20,
      "estimatedShipping": 9.99,
      "estimatedTotal": 593.17,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z",
      "status": "Active"
    }
  }
}

Use Cases:

Track quantity changes and purchase intent
Update inventory reservations
Monitor cart value changes
Analyze customer behavior patterns

cart.item_removed

Sent when a customer removes a product from their cart.

Event Type: cart.item_removed

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H4",
  "type": "cart.item_removed",
  "created_at": "2024-01-15T10:40:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:40:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "item": {
      "id": "880e8400-e29b-41d4-a716-446655440005",
      "productVariantId": "990e8400-e29b-41d4-a716-446655440006",
      "externalId": "shopify_7234567891",
      "externalVariantId": "shopify_43210987655",
      "productTitle": "USB-C Charging Cable",
      "variantTitle": "2 Meters",
      "sku": "CABLE-USBC-2M",
      "quantity": 1,
      "originalUnitPrice": 19.99,
      "unitPrice": 19.99,
      "originalTotalPrice": 19.99,
      "totalPrice": 19.99,
      "hasDiscount": false,
      "discountPercentage": null,
      "discountAmount": null,
      "addedAt": "2024-01-15T10:32:00.000Z",
      "updatedAt": null
    },
    "cartSummary": {
      "cartId": "770e8400-e29b-41d4-a716-446655440002",
      "itemCount": 1,
      "totalQuantity": 2,
      "subtotal": 539.98,
      "estimatedTax": 43.20,
      "estimatedShipping": 9.99,
      "estimatedTotal": 593.17,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:40:00.000Z",
      "status": "Active"
    }
  }
}

Use Cases:

Track cart abandonment reasons
Analyze product removal patterns
Trigger targeted promotions
Update inventory availability

cart.abandoned

Sent when a cart has been inactive for a configured period (typically 1 hour).

Event Type: cart.abandoned

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H5",
  "type": "cart.abandoned",
  "created_at": "2024-01-15T11:30:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T11:30:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "abandonedAt": "2024-01-15T11:30:00.000Z",
    "activeDuration": "PT1H",
    "cartSummary": {
      "cartId": "770e8400-e29b-41d4-a716-446655440002",
      "itemCount": 1,
      "totalQuantity": 2,
      "subtotal": 539.98,
      "estimatedTax": 43.20,
      "estimatedShipping": 9.99,
      "estimatedTotal": 593.17,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:40:00.000Z",
      "status": "Abandoned"
    }
  }
}

Use Cases:

Trigger abandoned cart recovery campaigns
Send reminder emails with cart contents
Offer time-limited discounts
Track cart abandonment rate
Send SMS reminders

Recovery Strategy Examples:

Send email reminder after 1 hour
Offer 5% discount after 24 hours
SMS reminder after 3 days
Final email with 15% discount after 1 week

cart.recovered

Sent when a customer resumes an abandoned cart.

Event Type: cart.recovered

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H6",
  "type": "cart.recovered",
  "created_at": "2024-01-16T08:15:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-16T08:15:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "recoveredAt": "2024-01-16T08:15:00.000Z",
    "originallyAbandonedAt": "2024-01-15T11:30:00.000Z",
    "cartSummary": {
      "cartId": "770e8400-e29b-41d4-a716-446655440002",
      "itemCount": 1,
      "totalQuantity": 2,
      "subtotal": 539.98,
      "estimatedTax": 43.20,
      "estimatedShipping": 9.99,
      "estimatedTotal": 593.17,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-16T08:15:00.000Z",
      "status": "Active"
    }
  }
}

Use Cases:

Track recovery campaign effectiveness
Measure cart recovery rate
Optimize recovery strategies
Stop abandoned cart emails

cart.cleared

Sent when all items are removed from a cart.

Event Type: cart.cleared

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H7",
  "type": "cart.cleared",
  "created_at": "2024-01-15T11:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T11:00:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "previousItems": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
        "externalId": "shopify_7234567890",
        "externalVariantId": "shopify_43210987654",
        "productTitle": "Premium Wireless Headphones",
        "variantTitle": "Black / Large",
        "sku": "WH-BLK-LG",
        "quantity": 2,
        "originalUnitPrice": 299.99,
        "unitPrice": 269.99,
        "originalTotalPrice": 599.98,
        "totalPrice": 539.98,
        "hasDiscount": true,
        "discountPercentage": 10.0,
        "discountAmount": 60.00,
        "addedAt": "2024-01-15T10:31:00.000Z",
        "updatedAt": "2024-01-15T10:35:00.000Z"
      }
    ],
    "previousTotal": 593.17
  }
}

Use Cases:

Track cart clearing behavior
Analyze customer indecision
Trigger re-engagement campaigns

cart.checkout_started

Sent when a customer begins the checkout process (cart converted to checkout).

Event Type: cart.checkout_started

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H8",
  "type": "cart.checkout_started",
  "created_at": "2024-01-15T10:35:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:35:00.000Z",
    "externalReference": null,
    "cartId": "770e8400-e29b-41d4-a716-446655440002",
    "checkoutId": "aa0e8400-e29b-41d4-a716-446655440007",
    "checkoutStartedAt": "2024-01-15T10:35:00.000Z",
    "items": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
        "externalId": "shopify_7234567890",
        "externalVariantId": "shopify_43210987654",
        "productTitle": "Premium Wireless Headphones",
        "variantTitle": "Black / Large",
        "sku": "WH-BLK-LG",
        "quantity": 2,
        "originalUnitPrice": 299.99,
        "unitPrice": 269.99,
        "originalTotalPrice": 599.98,
        "totalPrice": 539.98,
        "hasDiscount": true,
        "discountPercentage": 10.0,
        "discountAmount": 60.00,
        "addedAt": "2024-01-15T10:31:00.000Z",
        "updatedAt": "2024-01-15T10:35:00.000Z"
      }
    ],
    "totals": {
      "subtotal": 539.98,
      "shippingTotal": 9.99,
      "taxTotal": 43.20,
      "discountTotal": 60.00,
      "totalAmount": 593.17
    },
    "customer": {
      "customerId": "660e8400-e29b-41d4-a716-446655440001",
      "email": "customer@example.com",
      "phone": "+1234567890",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Use Cases:

Track checkout conversion rate
Measure high-intent customers
Trigger urgent remarketing campaigns
Monitor checkout funnel performance
Send checkout reminder notifications

Order Events

Order events track the lifecycle of customer orders. Note: These events are NOT sent for orders created or updated via SDK endpoints.

order.created

Sent after successful payment and order creation from your storefront.

Event Type: order.created

NOT sent when: Orders are created via POST /api/v1/orders (SDK endpoint)

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H9",
  "type": "order.created",
  "created_at": "2024-01-15T10:40:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T10:40:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "checkoutId": "aa0e8400-e29b-41d4-a716-446655440007",
    "placedAt": "2024-01-15T10:40:00.000Z",
    "orderStatus": "Pending",
    "customer": {
      "customerId": "660e8400-e29b-41d4-a716-446655440001",
      "email": "customer@example.com",
      "phone": "+1234567890",
      "firstName": "John",
      "lastName": "Doe"
    },
    "items": [
      {
        "id": "cc0e8400-e29b-41d4-a716-446655440009",
        "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
        "externalProductId": "shopify_7234567890",
        "externalVariantId": "shopify_43210987654",
        "productTitle": "Premium Wireless Headphones",
        "productImageUrl": "https://cdn.example.com/images/headphones.jpg",
        "variantTitle": "Black / Large",
        "sku": "WH-BLK-LG",
        "quantity": 2,
        "unitPrice": 269.99,
        "totalPrice": 539.98,
        "itemStatus": "Pending",
        "trackingNumber": null
      }
    ],
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "company": null,
      "address1": "123 Main Street",
      "address2": "Apt 4B",
      "city": "San Francisco",
      "province": "California",
      "country": "United States",
      "countryIsoCode": "US",
      "postalCode": "94102",
      "phone": "+1234567890"
    },
    "billingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "company": null,
      "address1": "123 Main Street",
      "address2": "Apt 4B",
      "city": "San Francisco",
      "province": "California",
      "country": "United States",
      "countryIsoCode": "US",
      "postalCode": "94102",
      "phone": "+1234567890"
    },
    "totals": {
      "subtotal": 539.98,
      "shippingTotal": 9.99,
      "taxTotal": 43.20,
      "discountTotal": 60.00,
      "totalAmount": 593.17
    },
    "paymentMethod": {
      "method": "credit_card",
      "display": "Visa ending in 4242",
      "last4": "4242",
      "brand": "Visa"
    },
    "deliveryInstructions": "Please leave at the front door"
  }
}

Use Cases:

Sync orders to fulfillment systems
Send order confirmation emails
Update inventory levels
Trigger accounting/ERP integration
Start shipping label generation
Update customer lifetime value

order.status_updated

Sent when order status changes through internal processes (payment confirmation, fulfillment updates).

Event Type: order.status_updated

NOT sent when: Order status is updated via PUT /api/v1/orders/{id}/status (SDK endpoint)

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H10",
  "type": "order.status_updated",
  "created_at": "2024-01-15T11:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T11:00:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "previousStatus": "Pending",
    "newStatus": "Confirmed",
    "statusUpdatedAt": "2024-01-15T11:00:00.000Z",
    "statusChangeReason": "Payment confirmed"
  }
}

Possible Status Values:

Pending - Order awaiting payment confirmation
Confirmed - Payment confirmed, ready for fulfillment
Processing - Order being prepared
Shipped - Order shipped to customer
Delivered - Order delivered to customer
Cancelled - Order cancelled
Refunded - Order refunded

Use Cases:

Update external order management systems
Trigger status-specific customer notifications
Update fulfillment workflow
Track order lifecycle metrics

order.confirmed

Sent when an order is confirmed (typically after payment verification).

Event Type: order.confirmed

NOT sent when: Order is confirmed via SDK API calls

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H11",
  "type": "order.confirmed",
  "created_at": "2024-01-15T11:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T11:00:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "previousStatus": "Pending",
    "newStatus": "Confirmed",
    "statusUpdatedAt": "2024-01-15T11:00:00.000Z",
    "statusChangeReason": "Payment verified"
  }
}

Use Cases:

Start fulfillment process
Reserve inventory
Notify warehouse systems
Send order confirmation to customer

order.shipped

Sent when order status changes to "Shipped" through internal fulfillment processes.

Event Type: order.shipped

NOT sent when: Order status is updated to "Shipped" via SDK API calls

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H12",
  "type": "order.shipped",
  "created_at": "2024-01-16T09:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-16T09:00:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "shippedAt": "2024-01-16T09:00:00.000Z",
    "estimatedDeliveryAt": "2024-01-18T17:00:00.000Z",
    "trackingInfo": [
      {
        "trackingNumber": "1Z999AA10123456784",
        "carrier": "UPS",
        "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
        "itemIds": ["cc0e8400-e29b-41d4-a716-446655440009"]
      }
    ],
    "shippedItems": [
      {
        "id": "cc0e8400-e29b-41d4-a716-446655440009",
        "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
        "externalProductId": "shopify_7234567890",
        "externalVariantId": "shopify_43210987654",
        "productTitle": "Premium Wireless Headphones",
        "productImageUrl": "https://cdn.example.com/images/headphones.jpg",
        "variantTitle": "Black / Large",
        "sku": "WH-BLK-LG",
        "quantity": 2,
        "unitPrice": 269.99,
        "totalPrice": 539.98,
        "itemStatus": "Shipped",
        "trackingNumber": "1Z999AA10123456784"
      }
    ],
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "company": null,
      "address1": "123 Main Street",
      "address2": "Apt 4B",
      "city": "San Francisco",
      "province": "California",
      "country": "United States",
      "countryIsoCode": "US",
      "postalCode": "94102",
      "phone": "+1234567890"
    }
  }
}

Use Cases:

Send shipping confirmation to customer
Provide tracking information
Update order status in external systems
Trigger delivery follow-up sequence

order.delivered

Sent when order status changes to "Delivered" through internal tracking.

Event Type: order.delivered

NOT sent when: Order status is updated to "Delivered" via SDK API calls

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H13",
  "type": "order.delivered",
  "created_at": "2024-01-18T14:30:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-18T14:30:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "deliveredAt": "2024-01-18T14:30:00.000Z",
    "deliveryConfirmation": "Delivered and signed by: John Doe",
    "deliveredItems": [
      {
        "id": "cc0e8400-e29b-41d4-a716-446655440009",
        "productVariantId": "990e8400-e29b-41d4-a716-446655440004",
        "externalProductId": "shopify_7234567890",
        "externalVariantId": "shopify_43210987654",
        "productTitle": "Premium Wireless Headphones",
        "productImageUrl": "https://cdn.example.com/images/headphones.jpg",
        "variantTitle": "Black / Large",
        "sku": "WH-BLK-LG",
        "quantity": 2,
        "unitPrice": 269.99,
        "totalPrice": 539.98,
        "itemStatus": "Delivered",
        "trackingNumber": "1Z999AA10123456784"
      }
    ]
  }
}

Use Cases:

Send delivery confirmation email
Request product review
Trigger post-purchase follow-up campaigns
Update customer purchase history
Measure delivery performance

order.cancelled

Sent when an order is cancelled through internal processes.

Event Type: order.cancelled

NOT sent when: Order is cancelled via PUT /api/v1/orders/{id}/cancel (SDK endpoint)

Payload Example:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H14",
  "type": "order.cancelled",
  "created_at": "2024-01-15T14:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "660e8400-e29b-41d4-a716-446655440001",
    "occurredAt": "2024-01-15T14:00:00.000Z",
    "externalReference": null,
    "orderId": "bb0e8400-e29b-41d4-a716-446655440008",
    "orderNumber": "ORD-2024-0001",
    "previousStatus": "Confirmed",
    "newStatus": "Cancelled",
    "statusUpdatedAt": "2024-01-15T14:00:00.000Z",
    "statusChangeReason": "Customer requested cancellation"
  }
}

Use Cases:

Send cancellation confirmation
Restore inventory
Process refunds
Update fulfillment systems
Track cancellation reasons

Product Events (Future Feature)

These events are not yet implemented but are prepared for future admin panel functionality.

Coming Soon

Product events will be enabled when product management is added to the admin panel. These events will NOT be sent for SDK operations to prevent webhook loops.

product.created (Future)

Will be sent when a product is created via the admin panel.

Event Type: product.created

NOT sent when: Products are created via SDK API calls

Expected Payload:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H15",
  "type": "product.created",
  "created_at": "2024-01-15T12:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": null,
    "occurredAt": "2024-01-15T12:00:00.000Z",
    "externalReference": null,
    "productId": "dd0e8400-e29b-41d4-a716-446655440010",
    "productTitle": "New Wireless Speaker",
    "description": "Portable Bluetooth speaker with 20-hour battery life",
    "externalProductId": null,
    "status": "Active",
    "category": "Electronics",
    "tags": ["audio", "wireless", "portable"],
    "variants": [
      {
        "id": "ee0e8400-e29b-41d4-a716-446655440011",
        "title": "Black",
        "sku": "SPK-BLK",
        "barcode": "1234567890123",
        "price": 149.99,
        "compareAtPrice": null,
        "inventoryQuantity": 100,
        "inventoryTracking": true,
        "externalVariantId": null,
        "status": "Active",
        "createdAt": "2024-01-15T12:00:00.000Z",
        "updatedAt": "2024-01-15T12:00:00.000Z"
      }
    ]
  }
}

product.updated (Future)

Will be sent when product details are modified via the admin panel.

Event Type: product.updated

NOT sent when: Products are updated via SDK API calls

Expected Payload:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H16",
  "type": "product.updated",
  "created_at": "2024-01-15T12:30:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": null,
    "occurredAt": "2024-01-15T12:30:00.000Z",
    "externalReference": null,
    "productId": "dd0e8400-e29b-41d4-a716-446655440010",
    "productTitle": "New Wireless Speaker",
    "externalProductId": null,
    "changes": {
      "description": "Updated: Premium Bluetooth speaker with 24-hour battery life",
      "price": 139.99
    },
    "previousValues": {
      "description": "Portable Bluetooth speaker with 20-hour battery life",
      "price": 149.99
    }
  }
}

product.variant_created (Future)

Will be sent when a variant is added to an existing product via admin panel.

Event Type: product.variant_created

Expected Payload:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H17",
  "type": "product.variant_created",
  "created_at": "2024-01-15T13:00:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": null,
    "occurredAt": "2024-01-15T13:00:00.000Z",
    "externalReference": null,
    "productId": "dd0e8400-e29b-41d4-a716-446655440010",
    "productTitle": "New Wireless Speaker",
    "externalProductId": null,
    "variant": {
      "id": "ff0e8400-e29b-41d4-a716-446655440012",
      "title": "White",
      "sku": "SPK-WHT",
      "barcode": "1234567890124",
      "price": 149.99,
      "compareAtPrice": null,
      "inventoryQuantity": 50,
      "inventoryTracking": true,
      "externalVariantId": null,
      "status": "Active",
      "createdAt": "2024-01-15T13:00:00.000Z",
      "updatedAt": "2024-01-15T13:00:00.000Z"
    }
  }
}

product.variant_updated (Future)

Will be sent when a variant is modified via admin panel.

Event Type: product.variant_updated

Expected Payload:

{
  "id": "evt_01J8X9Y2Z3A4B5C6D7E8F9G0H18",
  "type": "product.variant_updated",
  "created_at": "2024-01-15T13:30:00.000Z",
  "data": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": null,
    "occurredAt": "2024-01-15T13:30:00.000Z",
    "externalReference": null,
    "productId": "dd0e8400-e29b-41d4-a716-446655440010",
    "productTitle": "New Wireless Speaker",
    "externalProductId": null,
    "variant": {
      "id": "ee0e8400-e29b-41d4-a716-446655440011",
      "title": "Black",
      "sku": "SPK-BLK",
      "barcode": "1234567890123",
      "price": 139.99,
      "compareAtPrice": 149.99,
      "inventoryQuantity": 85,
      "inventoryTracking": true,
      "externalVariantId": null,
      "status": "Active",
      "createdAt": "2024-01-15T12:00:00.000Z",
      "updatedAt": "2024-01-15T13:30:00.000Z"
    },
    "changes": {
      "price": 139.99,
      "compareAtPrice": 149.99,
      "inventoryQuantity": 85
    },
    "previousValues": {
      "price": 149.99,
      "compareAtPrice": null,
      "inventoryQuantity": 100
    }
  }
}

Event Categories

Currently Active Events

Cart Events (8 events):

cart.created
cart.item_added
cart.item_updated
cart.item_removed
cart.abandoned
cart.recovered
cart.cleared
cart.checkout_started

Order Events (6 events):

order.created
order.status_updated
order.confirmed
order.shipped
order.delivered
order.cancelled

Future Events

Product Events (4 events - not yet active):

product.created
product.updated
product.variant_created
product.variant_updated

Next Steps

Webhooks Guide - Learn how to set up and secure webhooks
API Reference - Webhook management API documentation
Best Practices - Production-ready webhook implementation

Need Help?

Support: support@vesuviopay.com
API Reference: Detailed endpoint documentation
Community: Discord Community

Event Structure​

Cart Events​

cart.created​

cart.item_added​

cart.item_updated​

cart.item_removed​

cart.abandoned​

cart.recovered​

cart.cleared​

cart.checkout_started​

Order Events​

order.created​

order.status_updated​

order.confirmed​

order.shipped​

order.delivered​

order.cancelled​

Product Events (Future Feature)​

product.created (Future)​

product.updated (Future)​

product.variant_created (Future)​

product.variant_updated (Future)​

Event Categories​

Currently Active Events​

Future Events​

Next Steps​

Need Help?​

Event Structure

Cart Events

cart.created

cart.item_added

cart.item_updated

cart.item_removed

cart.abandoned

cart.recovered

cart.cleared

cart.checkout_started

Order Events

order.created

order.status_updated

order.confirmed

order.shipped

order.delivered

order.cancelled

Product Events (Future Feature)

product.created (Future)

product.updated (Future)

product.variant_created (Future)

product.variant_updated (Future)

Event Categories

Currently Active Events

Future Events

Next Steps

Need Help?