Skip to content
MothershipDevelopers

Webhook eventsShipments

Shipment status updated

Sent when a shipment's status changes.

EVENTshipment.status.updated
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:f62565f822a529243ac737572ee59c4a643c8f5cbb1091312beff66bd258e6e1
X-Mothership-Delivery-Id:3f6c1a9e-8b2d-4c7a-9e15-2d8b7f4a6c01
{
: "shipment.status.updated",
: {
: "ArrivedAtPickup",
: "EnrouteToPickup",
: "MS123456"
},
: "2026-10-08T15:04:05.000Z",
: 1,
: 16
}

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

The first event for a new shipment has newShipmentStatus set to Unallocated and no previousShipmentStatus key, so treat that key as optional.

A shipment can jump ahead, for example when its carrier doesn't report every status. You still get an event for each status along the way, sent in lifecycle order, each with the status before it. A jump from DriverAllocated to EnrouteToDelivery sends three events:

previousShipmentStatusnewShipmentStatus
DriverAllocatedEnrouteToPickup
EnrouteToPickupArrivedAtPickup
ArrivedAtPickupEnrouteToDelivery

The added events start at DriverAllocated and never include FindingDriver. A jump from Unallocated to EnrouteToPickup sends Unallocated to DriverAllocated, then DriverAllocated to EnrouteToPickup. A move back to an earlier status, or to Cancelled, sends one event.

Events can arrive out of order when one is retried. The event carries no time, and a step back is a real change, so don't drop an event because its status ranks below the one you have. When the current status matters, call Get shipment details.

Subscribing

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

Event data

data · 3 keys
  • newShipmentStatusstring

    The shipment's status now.

    UnallocatedFindingDriverDriverAllocatedEnrouteToPickupArrivedAtPickupEnrouteToDeliveryArrivedAtDeliveryCompletedWhat each value means →
  • previousShipmentStatusstring

    The status before this change. Missing from the first event of a new shipment.

    UnallocatedFindingDriverDriverAllocatedEnrouteToPickupArrivedAtPickupEnrouteToDeliveryArrivedAtDeliveryCompletedWhat each value means →
    can be missing
  • shipmentIdstring

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

Envelope

Same on every event
  • eventTypestring

    The event. Always shipment.status.updated 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.purchasedSent when a shipment is booked.proofOfDelivery.createdSent when a proof of delivery is first attached.Receiving webhooksVerify the signature, answer within 30 seconds, and handle retries and duplicates.