Webhooks

Webhooks provide real-time notifications about changes in the Mailship, including orders and products. We can configure the following webhooks for you:

Expedition status change
Expedition booked change
Product stock change
Product change
Stock advice status change

For more details on how webhooks are created, please refer to the Knowledge Base.

Webhook Payload Structure

Expedition status change

Triggered when an order status changes.

CODE

{
  "id": "5092699e-5b20-434e-91c8-fb332ac381d8",
  "status": "waiting_for_the_carrier",
  "timestamp": "2025-03-03T14:51:36+01:00",
  "orderNumber": "testOrder1"
}

Fields:

id: Unique identifier for the order update event.
status: The current status of the order.
timestamp: Timestamp of the status update.
orderNumber: Identifier of your order number.

The system sends webhooks when the expedition status changes.

Below is an overview of the statuses that may be included in the webhook payload. Status names are referenced exactly as written in API responses.

Status	Description
incorrect	The order contains invalid data and must be fixed by the client.
waiting_for_goods	Waiting for goods to be restocked.
stock_ok	“To be cofirmed” in Mailship. Waiting for your confirmation.
on_hold	The order is on hold.
awaiting_processing	The order is waiting for processing.
awaiting_reservation	The order is waiting for product reservation.
take_out	The order is being picked.
completion	The order is being packed.
waiting_for_the_carrier	The order is ready to be picked up by the carrier.
ready_to_takeover	Ready for customer pickup.
carrier_picked_up	The carrier has picked up the shipment.
delivered	The order has been delivered.
returning	The order is on its way back to warehouse.
returned	Our warehouse has processed the returned order.
canceled	The order has been canceled.

You can find more details about order statuses in our Knowledge Base.

Expedition booked change

Triggered when stock for an expedition has been booked.

CODE

{
  "id": "886bfee2-3907-4567-9de1-ed4a1b7b6e3a",
  "timestamp": "2025-03-03T14:51:05+01:00",
  "orderNumber": "testOrder2"
}

Fields:

id: Unique identifier for the expedition update event.
timestamp: Timestamp of the status update.
orderNumber: Order number related to this expedition booking.

Product stock change

Triggered when a product's stock level changes due to warehouse movements.

CODE

{
  "id": "3f42bed9-d65a-41f5-8333-464cc91e5b4c",
  "wms": "024a2209-17a6-4471-8c39-c0fabf4dbe62",
  "changes": {
    "booked": {
      "after": 1,
      "delta": -1,
      "before": 2
    },
    "missing": {
      "after": 0,
      "delta": 0,
      "before": 0
    },
    "incoming": {
      "after": 0,
      "delta": 0,
      "before": 0
    },
    "quantity": {
      "after": 349,
      "delta": -1,
      "before": 350
    },
    "available": {
      "after": 348,
      "delta": 0,
      "before": 348
    }
  },
  "productId": "f4e7815e-f61a-4e86-a499-dc52ecf29fa1",
  "timestamp": "2025-03-03T15:00:57+01:00",
  "warehouse": "0d579fb1-b27d-4ef6-8a10-44db10a13eb7",
  "productSku": "testProduct1",
  "internalSku": "testProduct1",
  "changeOriginators": [
    {
      "id": "a12e2ad6-8c7a-4160-bc97-7ac5bf1cf564",
      "type": "outbound_receipt",
      "clientId": null
    },
    {
      "id": "4ea33733-33b2-4b46-a56e-920315ad7242",
      "type": "expedition",
      "clientId": "testOrder2"
    }
  ]
}

Fields:

id: Unique identifier for the stock update event.
wms: Warehouse identifier.
changes: Stock change details with before, after, and delta values.
productId: Unique identifier of the affected product.
timestamp: Timestamp of the update.
warehouse: Physical warehouse ID where the stock change occurred.
productSku: Product’s SKU (EAN).
internalSku: Internal SKU of the product.
changeOriginators: List of events triggering the stock change.

Product change

Triggered when a product's SKU, internal SKU, or other details are modified.

CODE

{
  "id": "9e446787-cf42-4b35-8819-a4e581bfa0f5",
  "timestamp": "2025-03-03T15:00:53+01:00",
  "productSku": "8595717724834",
  "internalSku": "8595717724834"
}

Fields:

id: Unique identifier for the product update event.
timestamp: Timestamp of the update.
productSku: Product SKU (EAN) of the affected product.
internalSku: Internal SKU of the affected product.

Stock advice status change

Triggered when the status of a stock advice changes.

CODE

{
  "id": "f1edda63-800a-438d-a789-0209ecae38bf",
  "newStatus": "in_progress",
  "timestamp": "2025-03-03T14:48:02+01:00",
  "internalId": "testStockAdvice1"
}

Fields:

id: Unique identifier for the stock update event.
newStatus: New processing status of the stock advice (e.g., in_progress).
timestamp: Timestamp of the update.
internalId: Identifier of your stock advice.

The system sends webhooks when the stock advice status changes.

Below is an overview of the statuses that may be included in the webhook payload. Status names are referenced exactly as written in API responses.

Status	Description
new	New stock advice.
incorrect	The stock advice contains invalid data and must be fixed by the client.
waiting	“Awaiting inbound” in Mailship. The stock advice is waiting for processing.
in_progress	The stock advice is being processed.
partially_finished	Only some items have been stocked.
finished	All items have been stocked.
canceled	The stock advice has been canceled.
closed	The stock advice has been closed.

You can find more details about stock advice statuses in our Knowledge Base.

If you are interested in setting up a new webhook, please contact our customer support and provide the following information: URL and event type.