Shift dispatched event

Overview

The shift.dispatched webhook is sent when a bulk of orders from a delivery window (shift) is dispatched to delivery jobs. This webhook is part of Nash’s automated dispatch system for partner delivery workflows and provides real-time updates on the dispatch status of orders grouped by store location and shift name. Event Type: shift.dispatched
Entity Type: shift
Event Name: dispatched

When is this webhook triggered?

The webhook is triggered when:

Automatic Dispatch: The system automatically dispatches orders from delivery windows that have passed their cutoff time
Bulk Processing: Orders are grouped by organization, store location, pick shift name, and cutoff date
Validation Complete: All orders in the group pass validation checks before dispatch

Validation rules

Before orders are dispatched, the system validates each order against the following criteria:

Order-level validations

Delivery Window Status
- Delivery window status must be confirmed
- Orders with other statuses (e.g., pending, canceled) are skipped
Cutoff Time
- Cutoff time must have passed
- Orders with future cutoff times are not dispatched
Order Status
- Order must not already be in dispatched or archived status
- Prevents duplicate dispatches

Group-level validations

All orders in a store/shift group must meet the criteria above
If any order fails validation, it’s reported in the errors field
Successful orders still get dispatched; the webhook includes both successes and failures

Webhook payload structure

The webhook payload follows this structure:

{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_<activity_id>",
    "created_job_ids": ["job_<id1>", "job_<id2>", "job_<id3>"],
    "errors": {
      "ord_<order_id1>": "Error message describing the failure",
      "job_<job_id2>": "job_autodispatch_failure, Error dispatching to provider"
    }
  }
}

Payload fields

Field	Type	Description
`type`	string	Always `"shift"` for shift-related webhooks
`event`	string	Always `"dispatched"` for this webhook
`data.eventSourceId`	string	Activity ID that triggered the dispatch (format: `act_*`)
`data.created_job_ids`	array	List of successfully created job IDs (format: `job_*`)
`data.errors`	object	Dictionary mapping order/job IDs to error messages

Webhook scenarios

Scenario 1: complete success

All orders in the shift are successfully dispatched to jobs. Example Payload:

{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_7xK9mP2nQ4wL",
    "created_job_ids": [
      "job_8rY3nK7pL2xM",
      "job_5tW9mN3kP8yQ",
      "job_2zX6kL8rM5wN",
      "job_9vT4nM7pQ3xK"
    ],
    "errors": {}
  }
}

Interpretation:

4 orders were successfully dispatched
No errors occurred
Each job ID corresponds to one order being delivered
All orders from the shift are now in the delivery system

Scenario 2: partial success with validation errors

Some orders succeed while others fail validation checks. Example Payload:

{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_4mK8pN2wL9xQ",
    "created_job_ids": [
      "job_3nL7mK9pW2xQ",
      "job_6kM2nP8wL5yR"
    ],
    "errors": {
      "ord_5xW9mL3kP7yN": "order_validation_error: Delivery address is incomplete",
      "ord_8nK2pM7wL4xQ": "order_validation_error: Order has validation_errors: Missing customer phone number"
    }
  }
}

Interpretation:

2 orders successfully dispatched (jobs created)
2 orders failed validation and were not dispatched
Failed orders need to be corrected and re-dispatched manually
The validation error messages provide details on what needs to be fixed

Scenario 3: partial success with provider errors

Orders pass validation but fail when dispatching to the delivery provider. Example Payload:

{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_9pL3nM7kW2xQ",
    "created_job_ids": [
      "job_2kM8nL9pW5xQ",
      "job_7nK3mP2wL8yR"
    ],
    "errors": {
      "job_4xW9mL3kP7yN": "job_autodispatch_failure, Error dispatching to provider",
      "ord_8nK2pM7wL4xQ": "order_validation_error: Order has validation_errors: Missing customer phone number"
    }
  }
}

Interpretation:

2 orders successfully dispatched to the provider
1 order failed at the provider dispatch stage (after job creation)
1 order failed validation and was not dispatched
Provider errors may indicate capacity issues, service area restrictions, or provider API problems
Orders with provider errors may have jobs created but not accepted by the provider

Error types reference

Order validation errors

Order validation errors come from Nash’s order validation. See the full validation rules in Order validations. Common validation error patterns:

Required fields

Field	Error Message
Any required field	`required field`
`pickupFirstName` / `pickupBusinessName`	`required field if pickupBusinessName is not provided` / `required field if pickupFirstName is not provided`
`dropoffFirstName` / `dropoffBusinessName`	`required field if dropoffBusinessName is not provided` / `required field if dropoffFirstName is not provided`

Store location errors

Error Message	Meaning
`{store_location_id} does not exist`	Store location ID not found in organization
`{store_location_id} is deleted`	Store location has been deleted
`Error creating store {external_store_location_id}`	Failed to auto-create store location

Address and location errors

Error Message	Meaning
`Address not found`	Address could not be geocoded/parsed
`Pickup and dropoff places must be the different`	Same place_id used for pickup and dropoff
`Pickup and dropoff addresses must be the different`	Identical pickup and dropoff addresses
`Pickup and dropoff countries must be the same`	Cross-border delivery not allowed
`Distance between pickup and dropoff is {distance} miles, which exceeds your organization's maximum delivery distance of {max} miles.`	Distance exceeds org-specific limit
`Distance between pickup and dropoff locations is too large: {distance} miles. Limit is 300 miles.`	Distance exceeds global default limit

Phone number errors

Error Message	Meaning
`Invalid phone number`	Phone number format invalid for country
Phone validation errors	Various errors from phone number validation

Value and type errors

Field	Error Message	Meaning
`valueCents`, `tipAmountCents`, `itemsCount`	`value must be an integer`	Non-integer value provided
`weight`, `height`, `width`, `depth`, `volume`	`value must be a decimal number`	Non-numeric value provided
Numeric fields	`value must be greater than 0`	Zero or negative value
`valueCents`	`value must be more than 0`	Order value is zero or negative
`itemsCount`	`value must be more than 0 or null`	Items count is zero
`maxDeliveryFeeCents`	`value must be greater than 0`	Max fee is zero or negative
Name fields	`value must be a string`	Non-string value provided
Name fields	`value is too long: {length} > {max}`	Name exceeds maximum length (80 chars)

Delivery mode and datetime errors

Error Message	Meaning
`Valid values are {PackageDeliveryModeValues}`	Invalid delivery mode (must be `now` or `scheduled`)
`at least one value is required`	Scheduled mode requires at least one datetime field
`Time is in the past`	Datetime is earlier than current time (when not allowed)
`cannot be later than pickupEndTime`	`pickupStartTime` is after `pickupEndTime`
`cannot be later than dropoffEndTime`	`pickupEndTime` or `pickupStartTime` is after `dropoffEndTime`
`cannot be later than dropoffStartTime`	`pickupStartTime` is after `dropoffStartTime`

Currency and requirements errors

Field	Error Message	Meaning
`currency`	`Supported currencies are {SUPPORTED_CURRENCIES}`	Invalid currency code
`requirements`	`Supported values are {SUPPORTED_PACKAGE_REQUIREMENTS}`	Invalid package requirement
`minimumVehicleSize`	`Supported values are {VEHICLES_TO_SHOW_USERS}`	Invalid vehicle size

External ID errors

Error Message	Meaning
`'{external_id}' is used in other order(s): {order_ids}`	External ID already in use

Items errors

Error Message	Meaning
`The items data is invalid`	Items array contains invalid data structure

Provider dispatch errors

Error Message	Meaning	Action Required
`job_autodispatch_failure, Error dispatching to provider`	Provider API failure	Check provider status, retry manually if needed
`job_autodispatch_failure, Error dispatching to a job`	Job creation failed	Review job configuration and order details

​Overview

​When is this webhook triggered?

​Validation rules

​Order-level validations

​Group-level validations

​Webhook payload structure

​Payload fields

​Webhook scenarios

​Scenario 1: complete success

​Scenario 2: partial success with validation errors

​Scenario 3: partial success with provider errors

​Error types reference

​Order validation errors

​Required fields

​Store location errors

​Address and location errors

​Phone number errors

​Value and type errors

​Delivery mode and datetime errors

​Currency and requirements errors

​External ID errors

​Items errors

​Provider dispatch errors

Overview

When is this webhook triggered?

Validation rules

Order-level validations

Group-level validations

Webhook payload structure

Payload fields

Webhook scenarios

Scenario 1: complete success

Scenario 2: partial success with validation errors

Scenario 3: partial success with provider errors

Error types reference

Order validation errors

Required fields

Store location errors

Address and location errors

Phone number errors

Value and type errors

Delivery mode and datetime errors

Currency and requirements errors

External ID errors

Items errors

Provider dispatch errors