Skip to content
MothershipDevelopers

Webhook eventsShipments

Shipment purchased

Sent when a shipment is booked.

EVENTshipment.purchased
POST to your endpointSigned with HMAC-SHA256Retried for up to 4 days
RequestPOSThttps://your-server.example.com/webhooks/mothership
Content-Type:application/json
X-Mothership-Signature:1b9ca54e634d047a28f999eb5ada99b03c18322988c228dafeca5c321ec7edcf
X-Mothership-Delivery-Id:3f6c1a9e-8b2d-4c7a-9e15-2d8b7f4a6c01
{
: "shipment.purchased",
: {
: "2026-10-08T15:03:12.481Z",
: {
: [],
: "Los Angeles",
: "1700",
: {
: 34.0136514,
: -118.3738708
},
: [
"receiving@example.com"
],
: "Delivery Company Name",
: "0900",
: "+13103329380",
: "ChIJ8ZzvEBy6woARqY2BXgf4C2c",
: "CA",
: "3900 S La Cienega Blvd",
: "Suite A",
: "90056"
},
: "2026-10-09T08:00:00-07:00",
: "2026-10-09T17:00:00-07:00",
: [
{
: "Boxed auto parts",
: 60,
: 48,
: 2,
: "Pallet",
: 450,
: 40
}
],
: {
: [
"liftgate"
],
: "Los Angeles",
: "1900",
: {
: 34.0615517,
: -118.3536391
},
: [],
: "Pickup Company Name",
: "0900",
: "+12133293311",
: "ChIJr8ZJ4C-5woARC5xDOyEHvzQ",
: "CA",
: "5600 Wilshire Blvd",
: "90036"
},
: 312.48,
: "MS123456",
: "Unallocated"
},
: "2026-10-08T15:04:05.000Z",
: 1,
: 16
}

Hover a key to see what it means. Click it to jump to the field.

Mothership sends one shipment.purchased per shipment, seconds after the purchase completes. data is read then, so a stop or price that changed in those seconds goes out changed.

To follow the shipment from here, subscribe to shipment.status.updated too. Its first event, Unallocated, comes about the same time as this one. Don't rely on which arrives first.

Subscribing

Add shipment.purchased to a configuration's subscribedEvents with Create a webhook configuration or in the dashboard.

Event data

data · 9 keys
  • createdAtstring

    When the shipment was created, as an ISO 8601 string in UTC.

  • deliveryobject

    The delivery stop.

  • earliestPickupDatestring

    The start of the pickup window, as an ISO 8601 string in the pickup's time zone with its offset and no milliseconds, such as 2026-10-09T08:00:00-07:00. A zero offset is written Z.

  • estimatedDeliveryDatestring

    The end of the delivery window, in the delivery stop's time zone, written the same way as earliestPickupDate.

  • freightarray of objects

    The freight, one entry per line item.

  • pickupobject

    The pickup stop.

  • pricenumber

    What the shipment costs you, in dollars, such as 312.48. Rebill and invoice events send amounts in cents.

  • shipmentIdstring

    The shipment's reference number, such as MS123456. Pass it to Get shipment details.

  • statusstring

    The shipment's status when Mothership built the event, seconds after the purchase. Usually Unallocated, but a shipment that moved on in those seconds sends its newer status.

    UnallocatedFindingDriverDriverAllocatedEnrouteToPickupArrivedAtPickupEnrouteToDeliveryArrivedAtDeliveryCompletedWhat each value means →

Envelope

Same on every event
  • eventTypestring

    The event. Always shipment.purchased here. Route on it, and answer 2xx to types you don't handle.

  • sentAtstring

    When Mothership queued the event to send, as an ISO 8601 string in UTC. Every retry and resend carries the same value, so it does not say when this attempt went out.

  • deliveryAttemptinteger

    Which send of this event this is, starting at 1. Resends from the dashboard count too.

  • pendingRetriesinteger

    How many automatic attempts are left if this one fails. 0 on the last one.

Related

shipment.status.updatedSent when a shipment's status changes.billOfLading.createdSent when a bill of lading is first attached to a shipment.Receiving webhooksVerify the signature, answer within 30 seconds, and handle retries and duplicates.