About webhooks for event updates with Shipium

Webhooks are a convenient way for your organization to be notified automatically of shipment event updates. You can register for a webhook to be notified of events for each service:

• Carrier selection
• Label generation

You'll need to register a separate webhook for each service – one for carrier selection and one for labels – for which you wish to receive notifications. Once you register a webhook for your organization, the next shipment update for your event will send notifications to the API endpoint for events matching your selected data fields (e.g., eventType). You will receive webhook notifications whenever a carrier selection or label is created, updated, or deleted, depending on the webhooks you register.

This document guides you through the steps to register a webhook for your organization for either carrier selection or label generation. You can register for both webhooks to receive updates for both carrier selection and label generation. To start, you’ll need to access the Shipium Console. To register a webhook for tracking shipments with Shipium, you can refer to Use Webhooks for Tracking.

One webhook registered per application to be notified with carrier selection or label generation (or both) event updates

Your organization can use a Shipium webhook to receive shipment 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 shipment 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.

🎣

One webhook per application to be notified with updates

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

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

Steps to register your webhook

Once in the Shipium Console, you'll follow these instructions to register your organization's webhook.

1. In the navigation pane at left, navigate to Carrier Selection, and then Carrier Selection Webhooks.

   

2. Select the Add Webhook button to the far right of your screen, located near your organization's user account profile information. Any existing webhooks your organization has previously registered will appear on the Carrier Selection Webhooks screen. If your organization has no existing registered webhooks, this screen will contain no webhooks until you've registered your first one.

3. Complete the required Settings fields shown in the Add Carrier Selection Webhook screen.

   

   1. Name. Provide a descriptive name for your webhook. We suggest using a simple naming convention that uses the underscore symbol to separate each element of your webhook's intended use, such as {organization}_{action}_{app}_{version}.

      1. Use a descriptive name so it's easy to determine the nature of your webhook (e.g., OrganizationName_eastCostTrackingBroker_app1_v1 vs. service_123).
      2. If this webhook is being used as a test or is meant to be short lived, indicate such in the name (e.g., OrganizationName_eastCostTrackingBroker_app1_v1_**Test**).
      3. Avoid using abbreviations in your name if possible, for greater clarity (e.g., OrganizationNameeastCostTrackingBroker_app1_v1 vs. OrganizationName_ectBroker_app1_v1).

   2. Payload URL. Create a web app with a Uniform Resource Locator (URL) to use as your webhook to receive shipment event notifications. This is the endpoint deployed on your server to receive incoming webhook shipment events your organization has selected. Enter your Hypertext Transfer Protocol Secure (HTTPS) URL endpoint into the Payload URL field.

   3. Tenants. This field will only appear if your organization uses Shipium's Tenant feature.

      1. If your organization doesn't use Tenants, you can disregard this step.

      2. If you use Tenants, you may want to receive shipment updates for all tenants, only one tenant, or a subset of tenants. This field allows you to determine how to set up automatic shipment updates by tenant.

         • In the first screenshot that follows, All has been selected from the dropdown menu, meaning no further action is required to receive shipment updates for all your organization's tenants.

           

         • In the second screenshot that follows, individual tenants have been selected from the dropdown menu. The list continues to populate horizontally across the data field as you add desired tenants, whether just one or multiple.

           

   4. Add Additional Header. You may optionally add custom HTTP endpoint headers to be sent in the webhook event by providing the key and value for the header.

      

4. In the Event Type Select section, you'll select the event type for which you wish to be notified via the webhook you're creating. You must register a webhook separately for each event type.

   

5. For Status, Shipium automatically sets new webhooks to inactive by default. This allows your organization to test your webhook before activating it as well as create a webhook that you may not be ready to activate. The benefit to your organization is a safe testing environment before the webhook starts sending shipment event notifications to your organization's server.

   

6. Finally, send a test payload to your endpoint. You'll select the Test Event button in the row of your newly created webhook on the primary Carrier Selection Webhooks page. Refer to the Final Steps and Sample Webhook Call Content section below for confirmation information.

   

👍

How will I know I've successfully completed registration?

Net new shipment events will push to your designated endpoint as received once you've completed registration.

Shipment event types for your webhook

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

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 shipment 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 shipment event updates, for both carrier selection and label events.

This sample JavaScript Object Notation (JSON) message demonstrates the push event sent to your organization's endpoint for your registered webhook. When a webhook is published regarding a carrier selection or label event, it will contain an array with one or more updates.

"events": [ // List of events
      {
          "metadata": { // The metadata associated with this event
              "eventId": "string", // UUID identifying this event for debugging/idempotency purposes
              "eventTimestamp": "date-time", // UTC timestamp of when this event was generated in our system
              "eventType": "string", // Indicates what event occurred in our system
              "payloadSchemaVersion": "string", // The schema version of this event's payload (major)
              "testEvent": boolean // Indicates if this is a test notification instead of a real event
          },
          "payload": { // The actual event data associated with this event
            // eventType specific payload 
          }
      }
  ]

The elements in the above sample webhook message are described in the following table.

Sample webhook message for carrier selection or label create/update event

This sample JSON message demonstrates the example model of the push event for the carrier selection create and update event types sent to your organization's endpoint for your registered webhook. The same payload is used for the label create and update event types, with additional carrier label information populated.

⚠️ Note: This example contains only a single event; in production, multiple events in a single message may be common.

{
    "events": [
        {
            "metadata": {
                "eventId": "f8a2e5b7-c3d9-4f16-a7e8-b9c12d34e5f6",
                "eventTimestamp": "2025-04-11T04:10:17.309452085Z",
                "eventType": "carrier_selection_created",
                "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
                "payloadSchemaVersion": "v1",
                "testEvent": true
            },
            "payload": {
                "eventType": "carrier_selection_created",
                "shipiumShipmentId": "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6",
                "partnerShipmentId": "PARTNER-CUSTOMID-123",
                "fulfillmentContextId": "9ba10640-600a-4d3e-842f-4b6a6c535be6",
                "partnerFulfillmentContextId": null,
                "fulfillmentContext": "warehouse",
                "shippedDateTime": "2025-04-05T02:33:10.884Z",
                "shipmentTags": [],
                "orderedDateTime": "2025-04-05T01:33:10.83Z",
                "estimatedDeliveryDate": "2025-04-10T00:00:00Z",
                "testMode": false,
                "packagingType": {
                    "packagingMaterial": "box",
                    "linearDimensions": {
                        "linearUnit": "in",
                        "length": 9.0,
                        "width": 6.0,
                        "height": 3.0
                    }
                },
                "totalWeight": {
                    "weightUnit": "lb",
                    "weight": 2.58
                },
                "desiredDeliveryDate": "2025-04-10T03:59:59.999Z",
                "shipFromAddress": {
                    "countryCode": "US",
                    "region": "NV",
                    "postalCode": "89408",
                    "addressType": "commercial"
                },
                "destinationAddress": {
                    "countryCode": "US",
                    "region": "FL",
                    "postalCode": "33131",
                    "addressType": "residential"
                },
                "carrierSelection": {
                    "carrierSelectionId": "5e4d3c2b-1a9f-48e7-b6d5-c4f3e2d1b0a9",
                    "carrier": "lasership",
                    "carrierServiceMethodId": "lasership-routed-delivery-service-method-id",
                    "serviceMethodName": "LaserShip",
                    "carrierZoneId": "lasership-zone-5",
                    "calculatedBillableWeight": {
                        "weightUnit": "lb",
                        "weight": 3.0
                    },
                    "currencyCode": "usd",
                    "totalCost": 6.43,
                    "carrierCompareCost": 6.43,
                    "lineItems": [
                        {
                            "name": "base rate",
                            "rate": 6.00
                        },
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 2.65
                        },
                        {
                            "name": "Residential Ground Surcharge Modifier",
                            "rate": -2.65
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.86
                        },
                        {
                            "name": "Ground Fuel Surcharge Modifier",
                            "rate": -0.43
                        }
                    ],
                    "integratedLineItems": [
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 0.0,
                            "unmodifiedRate": 2.65,
                            "surchargeType": "residential_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Residential Ground Surcharge Modifier",
                                    "rate": -2.65,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        },
                        {
                            "name": "base rate",
                            "rate": 6.00,
                            "unmodifiedRate": 6.00,
                            "surchargeType": "base",
                            "surchargeModifiers": []
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.43,
                            "unmodifiedRate": 0.86,
                            "surchargeType": "fuel_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Ground Fuel Surcharge Modifier",
                                    "rate": -0.43,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        }
                    ],
                    "thirdPartyBilling": false,
                    "timeInTransitModel": "shipium_ml_model"
                },
                "isReturnLabel": false
            }
        },

    ]
}

Sample webhook message for carrier selection delete event

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

{
  "shipiumShipmentId": "ea284495-efe3-4dd2-80bd-d9c269e5286b",
  "partnerShipmentId": "CUS-123456",
  "carrierSelectionId": "a38578c5-e8ba-4023-8fb0-663e7394733e",
  "shipiumLabelId": null,
  "carrier": "ups",
  "carrierTrackingId": null,
  "shippedDateTime": "2024-08-27T08:07:34-07:00",
  "deleteDateTime": "2024-08-27T11:00:00-07:00"
}

Sample webhook message for label delete event

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

{
  "shipiumShipmentId": "ea284495-efe3-4dd2-80bd-d9c269e5286b",
  "partnerShipmentId": "CUS-123456",
  "carrierSelectionId": "a38578c5-e8ba-4023-8fb0-663e7394733e",
  "shipiumLabelId": "6ddf5809-7acb-4590-831e-7ce2773f9e45",
  "carrier": "ups",
  "carrierTrackingId": "1Z123456789",
  "shippedDateTime": "2024-08-27T08:07:34-07:00",
  "deleteDateTime": "2024-08-27T11:00:00-07:00"
}

Carrier selection and label create/update webhook payload elements defined

Data elements for carrier selection and label create and update shipment event types are defined in the following table.

Carrier selection and label delete webhook payload elements defined

The following table includes descriptions of data elements for carrier selection and label delete shipment event types.

FAQ

Q: Why are there two line item elements, called lineItems and integratedLineItems respectively?
A: The integratedLineItems element contains more detail and has a structure that makes it easier to understand how surcharges and surcharge modifiers are applied. You should consider the lineItems element to be deprecated.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support