Webhooks can optionally be sent to a configurable remote endpoint when specific events occur. Please refer to our Webhooks guide for more detail. Mothership will POST these payloads to registered endpoints within 1 minute of the triggering event.

The SHA256 signature of each payload can be found in the X-Mothership-Signature header of the webhook POST request and verified using the secretKey available on the Create Webhook Config or Fetch Webhook Config response bodies. See Validating webhooks for more information.

Shipment Purchased Event

The shipment.purchased event is posted to an organization's webhooks whenever a Shipment is purchased.

{
  "data": {
    "createdAt": "2025-03-19T17:38:59.745Z",
    "delivery": {
      "accessorials": [],
      "city": "Los Angeles",
      "closeTime": "1700",
      "coordinates": {
        "latitude": 34.0136514,
        "longitude": -118.3738708
      },
      "emails": [
        "deliveryemail@deliverycompany.com"
      ],
      "name": "Delivery Company Name",
      "openTime": "0900",
      "phoneNumber": "+13103329380",
      "placeId": "ex323dkgfj3askdn0f3",
      "street": "3900 S La Cienega Blvd",
      "subStreet": "A",
      "state": "CA",
      "zip": "90056"
    },
    "earliestPickupDate": "2025-03-19T18:00:00Z",
    "estimatedDeliveryDate": "2025-03-20T00:00:00Z",
    "freight": [
      {
        "description": "Cargo Item Description",
        "height": 60,
        "length": 48,
        "quantity": 2,
        "type": "Pallet",
        "weight": 450,
        "width": 42
      }
    ],
    "pickup": {
      "accessorials": [
        "liftgate"
      ],
      "city": "Los Angeles",
      "closeTime": "1900",
      "coordinates": {
        "latitude": 34.0615517,
        "longitude": -118.3536391
      },
      "emails": [],
      "name": "Pickup Company Name",
      "openTime": "1000",
      "phoneNumber": "+12133293311",
      "placeId": "fm113dkgfde2askdn0e2",
      "street": "5600 Wilshire Blvd",
      "state": "CA",
      "zip": "90036"
    },
    "price": 64,
    "shipmentId": "JXM9JN",
    "status": "Unallocated"
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "eventType": "shipment.purchased",
  "sentAt": "2025-03-19T17:42:59.745Z"
}

Shipment Status Updated Event

The shipment.status.udpated event is posted to an organization's webhooks whenever a Shipment's status is updated.

{
  "data": {
    "previousShipmentStatus": "FindingDriver",
    "newShipmentStatus": "DriverAllocated",
    "shipmentId": "JXM9JN"
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "eventType": "shipment.status.updated",
  "sentAt": "2025-03-19T19:31:11.124Z"
}

📘
See Shipment Statuses section for more details on shipment statuses.

Document Created Event

The .created event is posted when a document is attached to a shipment for the first time. Webhooks can be configured to subscribe to creation events of specific document types.

{
  "data": {
    "type": "billOfLading",
    "url": "https://s3-us-west-1.amazonaws.com/mothership-shipments-bill-of-lading/JXM9JN.pdf",
    "shipmentId": "JXM9JN",
    "expiresAt": "2025-03-19T19:46:05.883Z",
    "createdAt": "2025-03-19T19:31:05.883Z"
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "eventType": "billOfLading.created",
  "sentAt": "2025-03-19T19:31:10.883Z"
}

Document Updated Event

The .updated event is posted when a new version of a document type is attached to a shipment. Webhooks can be configured to subscribe to update events for specific document types.

{
  "data": {
    "type": "billOfLading",
    "url": "https://s3-us-west-1.amazonaws.com/mothership-shipments-bill-of-lading/JXM9JN.pdf",
    "shipmentId": "JXM9JN",
    "expiresAt": "2025-03-20T01:19:06.132Z",
    "updatedAt": "2025-03-20T01:04:06.132Z"
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "eventType": "billOfLading.updated",
  "sentAt": "2025-03-20T01:04:11.132Z"
}