E-commerce Webhooks

SmartCut can send webhook notifications to your server when e-commerce events occur. Configure your webhook endpoint URL and the events you want to receive in your organisation settings.

Delivery

Webhooks are sent as POST requests with a JSON body. Each request includes the following headers:

Header	Description
Content-Type	application/json
X-SmartCut-Timestamp	Unix timestamp (ms) of the delivery attempt
X-SmartCut-Delivery	Unique delivery ID (UUID)

Failed deliveries (5xx or network errors) are retried up to 3 times with delays of 1s, 5s, and 30s. Client errors (4xx) are not retried.

Events

Event	Description
order.created	A new order has been placed
order.status_changed	The order status has been updated
order.payment_completed	Payment has been received
inventory.decremented	Stock quantities have been reduced after an order

Order Webhook

Sent for order.created, order.status_changed, and order.payment_completed events.

Payload

{
  "event": "order.created",
  "orderId": "abc123",
  "organisationId": "org456",
  "timestamp": "2026-03-06T12:00:00.000Z",
  "data": {
    "status": "pending",
    "previousStatus": "draft",
    "paymentStatus": "paid",
    "customer": {
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+44 7700 900000"
    },
    "pricing": {
      "total": 149.99,
      "currency": "GBP",
      "itemsSubtotal": 129.99,
      "shippingCost": 20.00
    },
    "shipping": {
      "method": "standard",
      "address": {
        "line1": "123 High Street",
        "city": "London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      }
    },
    "itemCount": 3,
    "partsCount": 24,
    "createdAt": "2026-03-06T11:55:00.000Z",
    "results": [
      {
        "jobId": 12345,
        "saw": {},
        "stock": [],
        "parts": [],
        "cuts": [],
        "offcuts": [],
        "unusableParts": [],
        "metadata": {}
      }
    ]
  }
}

Fields

Top-level

Field	Type	Description
event	string	One of order.created, order.status_changed, order.payment_completed
orderId	string	Unique order identifier
organisationId	string	Your organisation ID
timestamp	string	ISO 8601 timestamp of when the webhook was sent

data

Field	Type	Required	Description
status	string	Yes	Current order status
previousStatus	string	No	Previous status (present on order.status_changed)
paymentStatus	string	No	Payment status
itemCount	number	Yes	Number of line items in the order
partsCount	number	Yes	Total number of individual parts
createdAt	string	Yes	ISO 8601 timestamp of order creation
results	array	No	Optimisation results for each job in the order, in V3 API response format

data.results[]

Each entry is a full V3 API response containing the optimisation result for one job in the order. See the V3 API documentation for the complete response schema.

Field	Type	Description
jobId	number	Job identifier
saw	object	Saw configuration used
stock	array	Stock items
parts	array	Parts with coordinates and properties
cuts	array	Cut instructions
offcuts	array	Remaining offcut pieces
unusableParts	array	Parts that could not be placed
metadata	object	Complete analysis and metrics (efficiency, waste, costs, material summary)

data.customer

Field	Type	Required	Description
name	string	Yes	Customer full name
email	string	Yes	Customer email address
phone	string	No	Customer phone number

data.pricing

Field	Type	Required	Description
total	number	Yes	Order total
currency	string	Yes	ISO 4217 currency code
itemsSubtotal	number	No	Subtotal before shipping
shippingCost	number	No	Shipping cost

data.shipping

Optional. Present when shipping details are available.

Field	Type	Required	Description
method	string	No	Shipping method name
address.line1	string	Yes	Street address
address.city	string	Yes	City
address.postalCode	string	Yes	Postal/ZIP code
address.country	string	Yes	ISO 3166-1 alpha-2 country code

Inventory Webhook

Sent when stock quantities are decremented after an order is processed.

Payload

{
  "event": "inventory.decremented",
  "orderId": "abc123",
  "organisationId": "org456",
  "timestamp": "2026-03-06T12:01:00.000Z",
  "data": {
    "changes": [
      {
        "stockId": "stock789",
        "stockName": "18mm White Melamine",
        "material": "Melamine",
        "thickness": 18,
        "dimensions": {
          "length": 2440,
          "width": 1220
        },
        "previousQuantity": 50,
        "newQuantity": 47,
        "decrementedBy": 3,
        "deleted": false
      }
    ]
  }
}

data.changes[]

Field	Type	Required	Description
stockId	string	Yes	Stock item ID
stockName	string	No	Human-readable stock name
material	string	No	Material type
thickness	number	No	Material thickness
dimensions.length	number	No	Stock length
dimensions.width	number	No	Stock width
previousQuantity	number	Yes	Quantity before decrement
newQuantity	number	Yes	Quantity after decrement
decrementedBy	number	Yes	Number of units consumed
deleted	boolean	No	Whether the stock item was fully consumed

Testing

Use the test endpoint to verify your webhook URL is reachable. A test webhook sends a simple payload:

{
  "event": "test",
  "timestamp": "2026-03-06T12:00:00.000Z",
  "message": "This is a test webhook from SmartCut"
}