Webhooks

MarketBox Event Schemas

Copy page

All MarketBox webhook events share a common envelope structure that wraps the event-specific data. This ensures consistent handling across all event types.

Event envelope

Every webhook payload contains these top-level fields:

Field	Type	Description
companyId	string	The unique identifier of the MarketBox company account.
eventId	string (UUID)	A unique identifier for this specific event. Use this to deduplicate events.
eventTimestamp	string (ISO 8601)	The timestamp when the event was generated.
eventType	string	The type of event (e.g., order.created, booking.updated).
eventData	object	The event-specific payload. Structure varies by event type.

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "97729135-6fdb-4fe2-80bc-d348874aba34",
  "eventTimestamp": "2026-01-20T05:17:16.903Z",
  "eventType": "client.created",
  "eventData": {
    // Event-specific data here
  }
}

---

Event types

• order.created
• booking.created
• booking.updated
• client.created
• client.updated
• waitlist.created

---

order.created

Triggered when a new order is created in MarketBox.

eventData.order

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier for the order.
orderNumber	integer	Yes	Human-readable order number.
serviceId	string	Yes	The ID of the service booked.
serviceName	string	Yes	The name of the service booked.
type	string	Yes	Order type: SINGLE, ONGOING, PACKAGE, or GROUP.
externalOrderId	string	No	Your external system's order ID (if provided during creation).
transactions	array	Yes	List of transactions associated with this order.
createdAt	string (ISO 8601)	Yes	When the order was created.
updatedAt	string (ISO 8601)	Yes	When the order was last updated.
currency	string	Yes	Three-letter ISO currency code (e.g., USD).
status	string	Yes	Order status: CONFIRMED, PAID, or PAIDBYPKGCRE.
client	object	Yes	The client who placed the order.
location	object	Yes	Service delivery location.
provider	object	Yes	The assigned service provider.

transactions[]

Field	Type	Required	Description
type	string	Yes	Transaction type: PAYMENT, NO_PAYMENT, REFUND, or ADDITIONAL_CHARGE.
timestamp	string (ISO 8601)	Yes	When the transaction occurred.
subtotal	number	Yes	Order subtotal before discounts and fees.
promoCodeDiscount	number	No	Discount amount from promo codes.
serviceFee	number	No	Service fee amount.
tax	number	No	Tax amount.
total	number	Yes	Final total charged.

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "97729135-6fdb-4fe2-80bc-d348874aba34",
  "eventTimestamp": "2026-01-20T14:30:00.000Z",
  "eventType": "order.created",
  "eventData": {
    "order": {
      "id": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
      "orderNumber": 10542,
      "serviceId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
      "serviceName": "In-Home Personal Training",
      "type": "SINGLE",
      "externalOrderId": "ext-order-789",
      "transactions": [
        {
          "type": "PAYMENT",
          "timestamp": "2026-01-20T14:30:00.000Z",
          "subtotal": 85.00,
          "promoCodeDiscount": 10.00,
          "serviceFee": 5.00,
          "tax": 6.00,
          "total": 86.00
        }
      ],
      "createdAt": "2026-01-20T14:30:00.000Z",
      "updatedAt": "2026-01-20T14:30:00.000Z",
      "currency": "USD",
      "status": "CONFIRMED",
      "client": {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "firstName": "Sarah",
        "lastName": "Johnson",
        "email": "sarah.johnson@example.com",
        "phone": "+1-555-123-4567",
        "notes": "Prefers morning sessions"
      },
      "location": {
        "addressLine1": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "IL",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "62701",
        "lat": 39.7817,
        "long": -89.6501
      },
      "provider": {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "firstName": "Mike",
        "lastName": "Thompson",
        "email": "mike.thompson@example.com",
        "phone": "+1-555-987-6543"
      }
    }
  }
}

---

booking.created

Triggered when a new booking is created. For package orders, multiple bookings may be included in the array.

eventData.bookings[]

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier for the booking.
startDateAndTime	string	Yes	Scheduled start date and time with timezone offset.
durationMins	integer	Yes	Duration of the booking in minutes.
status	string	Yes	Booking status: SCHEDULED, ARRIVED, COMPLETED, CANCELLED, or NO_SHOW.
timezone	string	Yes	IANA timezone identifier (e.g., America/Chicago).
externalBookingId	string	No	Your external system's booking ID (if provided).
externalOrderId	string	No	Your external system's order ID (if provided).
notes	string	No	Notes associated with the booking.
orderId	string (UUID)	Yes	The ID of the parent order.
orderNumber	integer	Yes	Human-readable order number.
serviceId	string	Yes	The ID of the service.
serviceName	string	Yes	The name of the service.
recurrence	array	No	For ONGOING orders only: array of RRULE strings defining the recurrence pattern.
client	object	Yes	The client for this booking.
provider	object	Yes	The assigned service provider.
location	object	Yes	Service delivery location.
createdAt	string (ISO 8601)	Yes	When the booking was created.
updatedAt	string (ISO 8601)	Yes	When the booking was last updated.

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "eventTimestamp": "2026-01-20T14:35:00.000Z",
  "eventType": "booking.created",
  "eventData": {
    "bookings": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
        "startDateAndTime": "2026-01-25T09:00:00-06:00",
        "durationMins": 60,
        "status": "SCHEDULED",
        "timezone": "America/Chicago",
        "externalBookingId": "ext-booking-456",
        "externalOrderId": "ext-order-789",
        "notes": "Client prefers back door entrance",
        "orderId": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
        "orderNumber": 10542,
        "serviceId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
        "serviceName": "In-Home Personal Training",
        "client": {
          "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "email": "sarah.johnson@example.com",
          "phone": "+1-555-123-4567",
          "notes": "Prefers morning sessions"
        },
        "provider": {
          "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
          "firstName": "Mike",
          "lastName": "Thompson",
          "email": "mike.thompson@example.com",
          "phone": "+1-555-987-6543"
        },
        "location": {
          "addressLine1": "742 Evergreen Terrace",
          "city": "Springfield",
          "state": "IL",
          "country": "United States",
          "countryCode": "US",
          "postalCode": "62701",
          "lat": 39.7817,
          "long": -89.6501
        },
        "createdAt": "2026-01-20T14:35:00.000Z",
        "updatedAt": "2026-01-20T14:35:00.000Z"
      }
    ]
  }
}

---

booking.updated

Triggered when a booking is updated (e.g., rescheduled, status changed).

eventData.bookings[]

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier for the booking.
startDateAndTime	string	Yes	Updated scheduled start date and time.
durationMins	integer	Yes	Duration of the booking in minutes.
status	string	Yes	Current booking status: SCHEDULED, ARRIVED, COMPLETED, CANCELLED, or NO_SHOW.
timezone	string	Yes	IANA timezone identifier.
externalBookingId	string	No	Your external system's booking ID.
externalOrderId	string	No	Your external system's order ID.
notes	string	No	Notes associated with the booking.
orderId	string (UUID)	Yes	The ID of the parent order.
orderNumber	integer	Yes	Human-readable order number.
serviceId	string	Yes	The ID of the service.
serviceName	string	Yes	The name of the service.
recurrence	array	No	For ONGOING orders: RRULE strings defining recurrence.
client	object	Yes	The client for this booking.
provider	object	Yes	The assigned service provider.
location	object	Yes	Service delivery location.
createdAt	string (ISO 8601)	Yes	When the booking was created.
updatedAt	string (ISO 8601)	Yes	When the booking was last updated.

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "b2c3d4e5-6789-01bc-def2-3456789012bc",
  "eventTimestamp": "2026-01-22T10:15:00.000Z",
  "eventType": "booking.updated",
  "eventData": {
    "bookings": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
        "startDateAndTime": "2026-01-25T10:00:00-06:00",
        "durationMins": 60,
        "status": "SCHEDULED",
        "timezone": "America/Chicago",
        "externalBookingId": "ext-booking-456",
        "externalOrderId": "ext-order-789",
        "notes": "Rescheduled from 9am to 10am",
        "orderId": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
        "orderNumber": 10542,
        "serviceId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
        "serviceName": "In-Home Personal Training",
        "client": {
          "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "email": "sarah.johnson@example.com",
          "phone": "+1-555-123-4567",
          "notes": "Prefers morning sessions"
        },
        "provider": {
          "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
          "firstName": "Mike",
          "lastName": "Thompson",
          "email": "mike.thompson@example.com",
          "phone": "+1-555-987-6543"
        },
        "location": {
          "addressLine1": "742 Evergreen Terrace",
          "city": "Springfield",
          "state": "IL",
          "country": "United States",
          "countryCode": "US",
          "postalCode": "62701",
          "lat": 39.7817,
          "long": -89.6501
        },
        "createdAt": "2026-01-20T14:35:00.000Z",
        "updatedAt": "2026-01-22T10:15:00.000Z"
      }
    ]
  }
}

---

client.created

Triggered when a new client is created in MarketBox.

eventData.client

Field	Type	Required	Description
id	string	Yes	Unique identifier for the client.
status	string	Yes	Client status: ACTIVE or INACTIVE.
deleted	boolean	Yes	Whether the client has been soft-deleted.
firstName	string	Yes	Client's first name.
lastName	string	Yes	Client's last name.
email	string	Yes	Client's email address.
phone	string	Yes	Client's phone number.
notes	string	No	Notes about the client.
sendAppointmentReminders	boolean	Yes	Whether the client has opted in to appointment reminders.
address	object	No	Client's address (if provided).
cardLastFourDigits	string	No	Last four digits of saved payment card.
createdAt	string (ISO 8601)	Yes	When the client was created.
updatedAt	string (ISO 8601)	Yes	When the client was last updated.
salesYTD	number	No	Total sales year-to-date.
salesMTD	number	No	Total sales month-to-date (last 30 days).
ordersYTD	integer	No	Total orders year-to-date.
ordersMTD	integer	No	Total orders month-to-date (last 30 days).

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "c3d4e5f6-7890-12cd-ef34-5678901234cd",
  "eventTimestamp": "2026-01-20T09:00:00.000Z",
  "eventType": "client.created",
  "eventData": {
    "client": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "ACTIVE",
      "deleted": false,
      "firstName": "Sarah",
      "lastName": "Johnson",
      "email": "sarah.johnson@example.com",
      "phone": "+1-555-123-4567",
      "notes": "Referred by existing client",
      "sendAppointmentReminders": true,
      "address": {
        "addressLine1": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "IL",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "62701",
        "lat": 39.7817,
        "long": -89.6501
      },
      "cardLastFourDigits": "4242",
      "createdAt": "2026-01-20T09:00:00.000Z",
      "updatedAt": "2026-01-20T09:00:00.000Z",
      "salesYTD": 0,
      "salesMTD": 0,
      "ordersYTD": 0,
      "ordersMTD": 0
    }
  }
}

---

client.updated

Triggered when a client's information is updated.

eventData.client

Field	Type	Required	Description
id	string	Yes	Unique identifier for the client.
status	string	Yes	Client status: ACTIVE or INACTIVE.
deleted	boolean	Yes	Whether the client has been soft-deleted.
firstName	string	Yes	Client's first name.
lastName	string	Yes	Client's last name.
email	string	Yes	Client's email address.
phone	string	Yes	Client's phone number.
notes	string	No	Notes about the client.
sendAppointmentReminders	boolean	Yes	Whether the client has opted in to appointment reminders.
address	object	No	Client's address.
cardLastFourDigits	string	No	Last four digits of saved payment card.
createdAt	string (ISO 8601)	Yes	When the client was created.
updatedAt	string (ISO 8601)	Yes	When the client was last updated.
salesYTD	number	No	Total sales year-to-date.
salesMTD	number	No	Total sales month-to-date.
ordersYTD	integer	No	Total orders year-to-date.
ordersMTD	integer	No	Total orders month-to-date.

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "d4e5f6a7-8901-23de-f456-7890123456de",
  "eventTimestamp": "2026-01-21T11:30:00.000Z",
  "eventType": "client.updated",
  "eventData": {
    "client": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "ACTIVE",
      "deleted": false,
      "firstName": "Sarah",
      "lastName": "Johnson-Smith",
      "email": "sarah.jsmith@example.com",
      "phone": "+1-555-123-4567",
      "notes": "Referred by existing client. Updated name after marriage.",
      "sendAppointmentReminders": true,
      "address": {
        "addressLine1": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "IL",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "62701",
        "lat": 39.7817,
        "long": -89.6501
      },
      "cardLastFourDigits": "4242",
      "createdAt": "2026-01-20T09:00:00.000Z",
      "updatedAt": "2026-01-21T11:30:00.000Z",
      "salesYTD": 172.00,
      "salesMTD": 172.00,
      "ordersYTD": 2,
      "ordersMTD": 2
    }
  }
}

---

waitlist.created

Triggered when a new waitlist entry is created by a prospective client.

eventData

Field	Type	Required	Description
clientProspect	object	Yes	Information about the prospective client.
requestedServices	array	Yes	Services the prospect is interested in.
location	object	Yes	Preferred service location.
requiredSkills	array	Yes	Skills the prospect requires from providers.
fromDateAndTime	string	No	Start of preferred availability window.
toDateAndTime	string	No	End of preferred availability window.
daysOfWeek	array	No	Preferred days of week (0=Sunday, 6=Saturday).
createdAt	string (ISO 8601)	Yes	When the waitlist entry was created.

eventData.clientProspect

Field	Type	Required	Description
firstName	string	Yes	Prospect's first name.
lastName	string	Yes	Prospect's last name.
email	string	Yes	Prospect's email address.
phone	string	No	Prospect's phone number.
message	string	No	Message or notes from the prospect.

eventData.requestedServices[]

Field	Type	Required	Description
id	string	Yes	Service ID.
name	string	Yes	Service name.

eventData.location

Field	Type	Required	Description
companyLocationId	string	No	Company location ID (if applicable).
companyLocationName	string	No	Company location name.
addressLine1	string	No	Street address.
addressLine2	string	No	Apartment, suite, etc.
city	string	No	City name.
state	string	No	State or province.
country	string	No	Country name.
countryCode	string	No	Two-letter country code.
postalCode	string	No	Postal or ZIP code.
lat	number	No	Latitude coordinate.
long	number	No	Longitude coordinate.

eventData.requiredSkills[]

Field	Type	Required	Description
id	string	Yes	Skill ID.
name	string	Yes	Skill name.

Example payload

Code
 
{
  "companyId": "7a4efb9c-472b-4336-b82b-78c405658442",
  "eventId": "f6a7b8c9-0123-45fa-b678-9012345678fa",
  "eventTimestamp": "2026-01-20T16:20:00.000Z",
  "eventType": "waitlist.created",
  "eventData": {
    "clientProspect": {
      "firstName": "James",
      "lastName": "Wilson",
      "email": "james.wilson@example.com",
      "phone": "+1-555-246-8135",
      "message": "Looking for weekly swimming lessons for my daughter"
    },
    "requestedServices": [
      {
        "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
        "name": "Kids Swimming Lessons"
      },
      {
        "id": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c",
        "name": "Beginner Swimming"
      }
    ],
    "location": {
      "companyLocationId": "a7b8c9d0-e1f2-4a3b-4c5d-6e7f8a9b0c1d",
      "companyLocationName": "Downtown Aquatic Center",
      "addressLine1": "500 Pool Lane",
      "city": "Springfield",
      "state": "IL",
      "country": "United States",
      "countryCode": "US",
      "postalCode": "62702",
      "lat": 39.7900,
      "long": -89.6441
    },
    "requiredSkills": [
      {
        "id": "b8c9d0e1-f2a3-4b4c-5d6e-7f8a9b0c1d2e",
        "name": "Child Instruction"
      }
    ],
    "fromDateAndTime": "2026-02-01T08:00:00-06:00",
    "toDateAndTime": "2026-02-28T18:00:00-06:00",
    "daysOfWeek": [1, 3, 5],
    "createdAt": "2026-01-20T16:20:00.000Z"
  }
}

---

Common sub-schemas

Client object

The client object appears in order, booking, and client events:

Field	Type	Required	Description
id	string	Yes	Unique client identifier.
firstName	string	Yes	Client's first name.
lastName	string	Yes	Client's last name.
email	string	Yes	Client's email address.
phone	string	No	Client's phone number.
notes	string	No	Notes about the client.

Provider object

The provider object appears in order and booking events:

Field	Type	Required	Description
id	string	Yes	Unique provider identifier.
firstName	string	Yes	Provider's first name.
lastName	string	Yes	Provider's last name.
email	string	Yes	Provider's email address.
phone	string	Yes	Provider's phone number.

Location object

The location object appears in order, booking, and client events:

Field	Type	Required	Description
addressLine1	string	Yes	Street address.
addressLine2	string	No	Apartment, suite, etc.
city	string	No	City name.
state	string	Yes	State or province.
country	string	Yes	Country name.
countryCode	string	No	Two-letter country code.
postalCode	string	Yes	Postal or ZIP code.
lat	number	Yes	Latitude coordinate.
long	number	Yes	Longitude coordinate.