API referenceGetting started

Webhooks

The events Mothership can POST to your server, and what each payload contains.

2 min read

Webhooks can optionally be sent to a configurable remote endpoint when specific events occur. See the webhooks guide to set one up, or manage them on the Webhooks settings page in the dashboard. Mothership will POST these payloads to registered endpoints within 1 minute of the triggering event.

Each request carries an X-Mothership-Delivery-Id header that stays the same across every attempt at one event, so you can tell a retry from a new 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 a webhook configuration or Retrieve a webhook configuration response bodies. See Validating webhook payloads for more information.

Events

Webhook event type	Sent when
billOfLading.created	A bill of lading is first attached to a shipment.
billOfLading.updated	A new version of a bill of lading is attached.
proofOfDelivery.created	A proof of delivery is first attached.
proofOfDelivery.updated	A new version of a proof of delivery is attached.
deliveryReceipt.created	A delivery receipt is first attached.
deliveryReceipt.updated	A new version of a delivery receipt is attached.
certificateOfInsurance.created	A certificate of insurance is attached.
shipment.purchased	A shipment is booked.
shipment.status.updated	A shipment's status changes.

Every request body has the same envelope. The contents of data depend on eventType.

Property	Description
`eventType`	The event, such as `shipment.purchased`.
`data`	The event data, described below.
`sentAt`	ISO 8601 datetime that Mothership sent this event.
`deliveryAttempt`	Times we have sent this event, including this attempt.
`pendingRetries`	Times we will re-attempt to send this event if this attempt fails.

Shipment purchased event

The shipment.purchased event is posted to an organization's webhooks whenever a shipment is purchased. data holds the shipment.

Sample Webhook Payloadjson

{
  "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": "MS123456",
    "status": "Unallocated"
  },
  "deliveryAttempt": 1,
  "pendingRetries": 16,
  "eventType": "shipment.purchased",
  "sentAt": "2025-03-19T17:42:59.745Z"
}

Shipment status updated event

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

Sample Webhook Payloadjson

{
  "eventType": "shipment.status.updated",
  "data": {
    "shipmentId": "MS123456",
    "previousShipmentStatus": "EnrouteToPickup",
    "newShipmentStatus": "ArrivedAtPickup"
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}

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.

Sample Webhook Payloadjson

{
  "eventType": "billOfLading.created",
  "data": {
    "shipmentId": "MS123456",
    "type": "billOfLading",
    "url": "https://files.mothership.com/MS123456/billOfLading.pdf",
    "expiresAt": "2026-10-15T15:04:05.000Z",
    "createdAt": "2026-10-08T15:03:58.000Z"
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}

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.

Sample Webhook Payloadjson

{
  "eventType": "billOfLading.updated",
  "data": {
    "shipmentId": "MS123456",
    "type": "billOfLading",
    "url": "https://files.mothership.com/MS123456/billOfLading.pdf",
    "expiresAt": "2026-10-15T15:04:05.000Z",
    "createdAt": "2026-10-08T15:03:58.000Z",
    "updatedAt": "2026-10-08T15:04:01.000Z"
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}

Document URLs expire at expiresAt. To download a document later, call List shipment documents for a fresh URL.