# Webhooks

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

Webhooks can optionally be sent to a configurable remote endpoint when specific events occur. See the [webhooks guide](https://developers.mothership.com/docs/webhook-create) to set one up, or manage them on the [Webhooks settings page in the dashboard](https://dashboard.mothership.com/settings/webhooks). 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](https://developers.mothership.com/reference/createwebhookconfig) or [Retrieve a webhook configuration](https://developers.mothership.com/reference/fetchwebhookconfig) response bodies. See [Validating webhook payloads](https://developers.mothership.com/docs/webhooks-validation) 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.

```json Sample Webhook Payload
{
  "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.

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

> [!NOTE]
> See [Shipment statuses](https://developers.mothership.com/reference/shipment-status) 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](https://developers.mothership.com/docs/webhook-create).

```json Sample Webhook Payload
{
  "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](https://developers.mothership.com/docs/webhook-create).

```json Sample Webhook Payload
{
  "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](https://developers.mothership.com/reference/listshipmentdocuments) for a fresh URL.