# About webhooks for the order lifecycle

The Pack App can send webhook notifications to your system to keep you updated on the status of your orders. These webhooks are sent out at key moments in the order lifecycle, allowing you to build powerful integrations and automate your workflows.

This document guides you through the steps to register your organization's webhook. To start, you’ll need to access the Pack App in the Shipium Console.

## One webhook registered per application to be notified with order lifecycle event updates

Your organization can use a Shipium webhook to receive order lifecycle event updates to one API endpoint (or application), and then manage those updates via your internal processing system or pass them to your internal customers.

For example, if you have customers A, B, and C that need to receive order lifecycle event updates automatically, you would register one Shipium webhook for Customer A, one for Customer B, and one for Customer C, with three unique API endpoints.

Shipium suggests creating one webhook per desired application for which your organization needs to receive tracking event updates.

Once you've registered your organization's webhook, you can disable, delete, and enable it via the Pack App in the Shipium Console. You also can view a summary of all your registered webhooks within the console.

# Steps to register your webhook

To receive these webhook notifications, you will need to configure a webhook endpoint in your Shipium account settings. Please contact your Shipium account manager for assistance with setting up your webhooks.

# Order lifecycle event types for your webhook

The following table includes the event metadata event types that can be returned for an order lifecycle event notification. Each event type needs its own webhook registration; however, you can point all registered webhooks at the same API.

| Event type for webhook | Description |
| --- | --- |
| Order Created | Signals that a new order has been successfully ingested by Shipium |
| Order Updated | Notifies of any significant changes to the order details (e.g., quantity changes, address updates) |
| Order Shipped | Indicates that a shipment has been created for the order, and a label has been generated |
| Order Cancelled | Confirms that an order has been cancelled within the Pack App |
| Order Completed | Signifies that all items within an order have been shipped, marking the end of the fulfillment process for that order |

# Final steps and sample webhook call content

This section provides instructions for responding successfully to your webhook's initial call as well as sample webhook messages as they would appear as incoming order lifecycle event updates.

## How to respond to your first webhook call

Once you've successfully registered your organization's webhook, you will start receiving webhook calls. Upon receipt of your webhook call, you'll need to respond with an appropriate Hypertext Transfer Protocol (HTTP) status code to acknowledge successful receipt of your webhook call. Your response must:

- be an HTTP status code within the 200-299 range; and
- be delivered within 3 seconds of receiving the webhook call.

## Shipium's automated response to your newly registered webhook

Once you've registered your organization's webhook, Shipium:

- will retry the webhook three times if a 200-level HTTP code response is not received within 3 seconds, as required;
- will log this as an error; and
- may decide to mark your API endpoint as broken if multiple errors are received.

## Webhook retry logic

If a webhook push fails to deliver to the target location, the Shipium platform employs automated retry logic. This is not the same as guaranteed delivery of webhooks. If your organization’s system or webhook endpoint is down for an extended period, retries may not deliver the payload. Our webhooks have the below retry/backoff policy for new webhook setups. We will configure separate policies if there are recurring performance issues with a managed endpoint we are publishing to.

**Backoff Policy for Webhooks**

- Maximum Delivery Attempt Count = 4
- Backoffs per Attempt:
  - Attempt #1 = No backoff
  - Attempt #2 Backoff = 1 hour
  - Attempt #3 Backoff = 4 hours
  - Attempt #4 Backoff = 16 hours
- Maximum Backoff Time/Expires After = 24 hours

## Sample webhook messages

This section provides sample expected webhook messages as they would appear when delivering order lifecycle event updates.

### Sample webhook message for order created or order updated event

This sample JSON message demonstrates the example model of the push event for the order create and order update event types sent to your organization's endpoint for your registered webhook. The same payload is used for the order create and order update event types.

```json
{
  "eventId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "eventType": "order_created",
  "tenantId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
  "shipiumOrderId": "ord_2b4a6c8e-1f3d-5b7f-9h1j-3k5m7o9q1s3u",
  "partnerOrderId": "ACME-ORDER-789456",
  "orderStatus": "created",
  "orderEventDateTime": "2025-09-22T15:30:45.123Z",
  "fulfillmentType": "dropship",
  "orderSource": "store",
  "associatedIdentifiers": [
    "ACME-INTERNAL-12345",
    "CAMPAIGN-FALL2025"
  ],
  "orderedDateTime": "2025-09-22T15:29:12.456Z",
  "orderItemQuantities": [
    {
      "productId": "SKU-WIDGET-001",
      "quantity": 2
    },
    {
      "productId": "SKU-GADGET-XL-BLUE",
      "quantity": 1
    }
  ],
  "shipFromAddress": {
    "name": "ACME Fulfillment Center",
    "addressLine1": "1500 Industrial Blvd",
    "addressLine2": "Suite 200",
    "city": "Las Vegas",
    "region": "NV",
    "postalCode": "89408",
    "countryCode": "US",
    "addressType": "commercial",
    "phoneNumber": "+1-555-123-4567"
  },
  "originId": "warehouse_lv_01",
  "destinationAddress": {
    "name": "John Smith",
    "addressLine1": "123 Ocean Drive",
    "addressLine2": "Apt 4B",
    "city": "Miami",
    "region": "FL",
    "postalCode": "33131",
    "countryCode": "US",
    "addressType": "residential",
    "phoneNumber": "+1-555-987-6543",
    "email": "john.smith@email.com"
  },
  "shipOption": "ground",
  "customsInfo": {
    "contentType": "merchandise",
    "contentDescription": "Electronic accessories",
    "incoterm": "DAP",
    "customsItems": [
      {
        "description": "Wireless charging widget",
        "quantity": 2,
        "unitValue": {
          "amount": 29.99,
          "currencyCode": "USD"
        },
        "weight": {
          "value": 0.5,
          "unit": "lb"
        },
        "hsCode": "8504.40.95",
        "countryOfOrigin": "CN"
      }
    ]
  },
  "currencyCode": "USD",
  "totalDeclaredValue": {
    "amount": 89.97,
    "currencyCode": "USD"
  },
  "orderFulfillmentParameters": {
    "priorityLevel": "standard",
    "packagingPreference": "minimal",
    "deliveryInstructions": "Leave at front door",
    "insuranceRequired": false,
    "signatureRequired": false,
    "saturdayDelivery": false,
    "expeditedProcessing": false
  }
}
```

### Sample webhook message for order shipped event

This sample JSON message demonstrates the example model of the push event for the order shipped event type sent to your organization's endpoint for your registered webhook.

```json
{
  "eventId": "f3e7b8c2-9d1a-4f6e-8b2c-5d7f9a1e3b6d",
  "eventType": "order_shipped",
  "tenantId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
  "shipiumOrderId": "ord_2b4a6c8e-1f3d-5b7f-9h1j-3k5m7o9q1s3u",
  "partnerOrderId": "ACME-ORDER-789456",
  "orderStatus": "partially_shipped",
  "orderEventDateTime": "2025-09-23T10:15:32.789Z",
  "shipiumShipmentId": "ship_8a2f4e6b-3c5d-7f9a-1e3b-5d7f9a1e3b6d",
  "partnerShipmentId": "ACME-SHIP-789456-001",
  "type": "forward",
  "carrierTrackingId": "1Z999AA1234567890",
  "carrier": "ups",
  "carrierServiceMethodId": "ups-ground-service-method-id",
  "shipFromAddress": {
    "name": "ACME Fulfillment Center",
    "addressLine1": "1500 Industrial Blvd",
    "addressLine2": "Suite 200",
    "city": "Las Vegas",
    "region": "NV",
    "postalCode": "89408",
    "countryCode": "US",
    "addressType": "commercial",
    "phoneNumber": "+1-555-123-4567"
  },
  "originId": "warehouse_lv_01",
  "destinationAddress": {
    "name": "John Smith",
    "addressLine1": "123 Ocean Drive",
    "addressLine2": "Apt 4B",
    "city": "Miami",
    "region": "FL",
    "postalCode": "33131",
    "countryCode": "US",
    "addressType": "residential",
    "phoneNumber": "+1-555-987-6543",
    "email": "john.smith@email.com"
  },
  "fulfillmentContext": "warehouse",
  "fulfillmentContextId": "9ba10640-600a-4d3e-842f-4b6a6c535be6",
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 12.0,
      "width": 9.0,
      "height": 6.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 1.8
  },
  "shippedOrderItemQuantities": [
    {
      "productId": "SKU-WIDGET-001",
      "quantity": 2
    }
  ],
  "unshippedOrderItemQuantities": [
    {
      "productId": "SKU-GADGET-XL-BLUE",
      "quantity": 1
    }
  ]
}
```

### Sample webhook message for order cancelled event

This sample JSON message demonstrates the example model of the push event for the order cancelled event type sent to your organization's endpoint for your registered webhook.

```json
{
  "eventId": "c9f2e8a1-6b4d-3e7f-a2c5-8f1b4e7a2d5c",
  "eventType": "order_cancelled",
  "tenantId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
  "shipiumOrderId": "ord_2b4a6c8e-1f3d-5b7f-9h1j-3k5m7o9q1s3u",
  "partnerOrderId": "ACME-ORDER-789456",
  "orderStatus": "cancelled",
  "orderEventDateTime": "2025-09-22T16:45:18.234Z",
  "unshippedOrderItemQuantities": [
    {
      "productId": "SKU-WIDGET-001",
      "quantity": 2
    },
    {
      "productId": "SKU-GADGET-XL-BLUE",
      "quantity": 1
    }
  ]
}
```

### Sample webhook message for order completed event

This sample JSON message demonstrates the example model of the push event for the order completed event type sent to your organization's endpoint for your registered webhook.

```json
{
  "eventId": "e7d3f9b5-2a8c-4f1e-9b6d-7c2f5a8e1b4d",
  "eventType": "order_completed",
  "tenantId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
  "shipiumOrderId": "ord_2b4a6c8e-1f3d-5b7f-9h1j-3k5m7o9q1s3u",
  "partnerOrderId": "ACME-ORDER-789456",
  "orderStatus": "completed",
  "orderEventDateTime": "2025-09-24T14:22:07.567Z"
}
```

### Pack App order lifecycle webhook payload elements defined

Data elements for the Pack App order lifecycle event types are defined in the following tables.

#### Payload elements common to all event types

| Element | Details |
| --- | --- |
| `eventId` | **Type:** String<br>**Description:** A unique identifier associated with this event for debugging/idempotency purposes |
| `eventType` | **Type:** String (enumeration)<br>**Description:** The type of order lifecycle event this message represents |
| `tenantId` | **Type:** String<br>**Description:** The unique identifier for the tenant; when present, this is used to indicate the tenant associated with the order. |
| `shipiumOrderId` | **Type:** String<br>**Description:** The unique identifier for the order within Shipium's system |
| `partnerOrderId` | **Type:** String<br>**Description:** The unique identifier that your organization uses for the order |
| `orderStatus` | **Type:** String<br>**Description:** The current status of the order (e.g., "created", "partially_shipped", "shipped", "cancelled", "completed") |
| `orderEventDateTime` | **Type:** String (date-time)<br>**Description:** UTC timestamp of when this order event occurred in the Shipium system in ISO 8601 format |

#### Payload elements specific to order created and order updated event types

| Element | Details |
| --- | --- |
| `fulfillmentType` | **Type:** String<br>**Description:** The type of fulfillment for this order (e.g., "dropship", "warehouse", "3pl", "direct") |
| `orderSource` | **Type:** String<br>**Description:** The source system or channel where the order originated (e.g., "api", "manual") |
| `associatedIdentifiers` | **Type:** Array<br>**Description:** Additional identifiers associated with the order (e.g., internal reference numbers, campaign IDs) |
| `orderedDateTime` | **Type:** String (date-time)<br>**Description:** UTC timestamp of when the order was originally placed in ISO 8601 format |
| `orderItemQuantities.productId` | **Type:** String<br>**Description:** The unique identifier for the product/SKU |
| `orderItemQuantities.quantity` | **Type:** Integer (int32)<br>**Description:** The quantity of this product in the order |
| `shipFromAddress.name` | **Type:** String<br>**Description:** Name of the shipping location or facility |
| `shipFromAddress.addressLine1` | **Type:** String<br>**Description:** Primary address line |
| `shipFromAddress.addressLine2` | **Type:** String<br>**Description:** Secondary address line |
| `shipFromAddress.city` | **Type:** String<br>**Description:** City name |
| `shipFromAddress.region` | **Type:** String<br>**Description:** State, province, or region code |
| `shipFromAddress.postalCode` | **Type:** String<br>**Description:** Postal or ZIP code |
| `shipFromAddress.countryCode` | **Type:** String<br>**Description:** The 2-letter ISO 3166-1 country code |
| `shipFromAddress.addressType` | **Type:** String (enumeration)<br>**Description:** The type of shipping address |
| `shipFromAddress.phoneNumber` | **Type:** String<br>**Description:** Phone number for the shipping location |
| `originId` | **Type:** String<br>**Description:** The unique identifier for the origin/fulfillment location |
| `destinationAddress.name` | **Type:** String<br>**Description:** Recipient's name |
| `destinationAddress.addressLine1` | **Type:** String<br>**Description:** Primary address line |
| `destinationAddress.addressLine2` | **Type:** String<br>**Description:** Secondary address line |
| `destinationAddress.city` | **Type:** String<br>**Description:** City name |
| `destinationAddress.region` | **Type:** String<br>**Description:** State, province, or region code |
| `destinationAddress.postalCode` | **Type:** String<br>**Description:** Postal or ZIP code |
| `destinationAddress.countryCode` | **Type:** String<br>**Description:** The 2-letter ISO 3166-1 country code |
| `destinationAddress.addressType` | **Type:** String (enumeration)<br>**Description:** The type of delivery address |
| `destinationAddress.phoneNumber` | **Type:** String<br>**Description:** Recipient's phone number |
| `destinationAddress.email` | **Type:** String<br>**Description:** Recipient's email address |
| `shipOption` | **Type:** String<br>**Description:** The shipping service level requested (e.g., "ground", "express", "overnight") |
| `customsInfo` | **Type:** Object<br>**Description:** Customs information for international shipments |
| `customsInfo.contentType` | **Type:** String<br>**Description:** Type of contents (e.g., "merchandise", "gift", "documents") |
| `customsInfo.contentDescription` | **Type:** String<br>**Description:** Description of the package contents |
| `customsInfo.incoterm` | **Type:** String<br>**Description:** International commercial terms (e.g., "DAP", "DDP", "FOB") |
| `customsInfo.customsItems.description` | **Type:** String<br>**Description:** Description of the customs item |
| `customsInfo.customsItems.quantity` | **Type:** Integer (int32)<br>**Description:** Quantity of this item |
| `customsInfo.customsItems.unitValue.amount` | **Type:** Number<br>**Description:** Monetary amount |
| `customsInfo.customsItems.unitValue.currencyCode` | **Type:** String<br>**Description:** The 3-letter ISO 4217 currency code |
| `customsInfo.customsItems.weight.value` | **Type:** Number<br>**Description:** Weight value |
| `customsInfo.customsItems.weight.unit` | **Type:** String<br>**Description:** Weight unit (e.g., "lb", "kg", "oz", "g") |
| `customsInfo.customsItems.hsCode` | **Type:** String<br>**Description:** Harmonized System classification code |
| `customsInfo.customsItems.countryOfOrigin` | **Type:** String<br>**Description:** The 2-letter ISO 3166-1 country code of origin |
| `currencyCode` | **Type:** String<br>**Description:** The 3-letter ISO 4217 currency code for the order value |
| `totalDeclaredValue.amount` | **Type:** Number<br>**Description:** Total monetary amount of the declared value of the order |
| `totalDeclaredValue.currencyCode` | **Type:** String<br>**Description:** The 3-letter ISO 4217 currency code |
| `orderFulfillmentParameters.priorityLevel` | **Type:** String<br>**Description:** Priority level for processing (e.g., "standard", "expedited", "rush") |
| `orderFulfillmentParameters.packagingPreference` | **Type:** String<br>**Description:** Packaging preference (e.g., "minimal", "standard", "protective") |
| `orderFulfillmentParameters.deliveryInstructions` | **Type:** String<br>**Description:** Special delivery instructions |
| `orderFulfillmentParameters.insuranceRequired` | **Type:** Boolean<br>**Values:** true or false<br>**Description:** Whether insurance is required for the shipment |
| `orderFulfillmentParameters.signatureRequired` | **Type:** Boolean<br>**Values:** true or false<br>**Description:** Whether signature confirmation is required |
| `orderFulfillmentParameters.saturdayDelivery` | **Type:** Boolean<br>**Values:** true or false<br>**Description:** Whether Saturday delivery is requested |
| `orderFulfillmentParameters.expeditedProcessing` | **Type:** Boolean<br>**Values:** true or false<br>**Description:** Whether expedited processing is requested |

#### Payload elements specific to order shipped event type

| Element | Details |
| --- | --- |
| `shipiumShipmentId` | **Type:** String<br>**Description:** The unique identifier for the shipment within Shipium's system |
| `partnerShipmentId` | **Type:** String<br>**Description:** The unique identifier that your organization uses for the shipment |
| `type` | **Type:** String (enumeration)<br>**Description:** The type of shipment (forward shipment or return) |
| `carrierTrackingId` | **Type:** String<br>**Description:** The tracking number provided by the carrier |
| `carrier` | **Type:** String<br>**Description:** The carrier that will handle the shipment |
| `carrierServiceMethodId` | **Type:** String<br>**Description:** The carrier service method identifier |
| `fulfillmentContext` | **Type:** String<br>**Description:** The context of fulfillment (e.g., "warehouse", "3pl", "dropship", "store") |
| `fulfillmentContextId` | **Type:** String<br>**Description:** The Shipium-generated unique identifier for the fulfillment context |
| `packagingType.packagingMaterial` | **Type:** String (enumeration)<br>**Description:** The type of packaging material used |
| `packagingType.linearDimensions.linearUnit` | **Type:** String (enumeration)<br>**Description:** The unit of measurement for dimensions |
| `packagingType.linearDimensions.length` | **Type:** Number<br>**Description:** Length of the package |
| `packagingType.linearDimensions.width` | **Type:** Number<br>**Description:** Width of the package |
| `packagingType.linearDimensions.height` | **Type:** Number<br>**Description:** Height of the package |
| `totalWeight.weightUnit` | **Type:** String (enumeration)<br>**Description:** The unit of measurement for weight |
| `totalWeight.weight` | **Type:** Number<br>**Description:** The weight value |
| `shippedOrderItemQuantities` | **Type:** Array<br>**Description:** List of products and quantities that were shipped in this shipment |
| `shippedOrderItemQuantities.productId` | **Type:** String<br>**Description:** The unique identifier for the shipped product/SKU |
| `shippedOrderItemQuantities.quantity` | **Type:** Integer (int32)<br>**Description:** The quantity of this product that was shipped |
| `unshippedOrderItemQuantities` | **Type:** Array<br>**Description:** List of products and quantities that remain unshipped |
| `unshippedOrderItemQuantities.productId` | **Type:** String<br>**Description:** The unique identifier for the unshipped product/SKU |
| `unshippedOrderItemQuantities.quantity` | **Type:** Integer (int32)<br>**Description:** The quantity of this product that remains unshipped |

#### Payload elements specific to order completed event type

| Element | Details |
| --- | --- |
| `unshippedOrderItemQuantities` | **Type:** Array<br>**Description:** List of products and quantities that remain unshipped |
| `unshippedOrderItemQuantities.productId` | **Type:** String<br>**Description:** The unique identifier for the unshipped product/SKU |
| `unshippedOrderItemQuantities.quantity` | **Type:** Integer (int32)<br>**Description:** The quantity of this product that remains unshipped |