Using Webhooks to Automatically Receive Tracking Updates

Automatically receive tracking updates as they occur.

Suggest Edits

Webhook overview

A webhook is a type of application programming interface (API) that's driven by events instead of requests. A webhook enables one program to transmit data to another program when an event takes place.

Webhooks differ from APIs in that the program sending the data initiates communication rather than the program receiving data. Webhooks can provide a less involved solution for enabling real-time notifications and data updates without the need to develop a full-scale API.

Why you might use a webhook with Shipium

Webhooks are a convenient way for your organization to be notified automatically of tracking event updates, eliminating the need to repeatedly call the Carrier Tracking Search API to check a tracking event status. Once you register a webhook for your organization, the next tracking update for your event will send notifications to the API endpoint for trackings matching your selected data fields (e.g., eventType).

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

General steps and requirements for each webhook registration

One webhook registered per application to be notified with tracking event updates

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

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

Steps to register your webhook

🚧

These steps are not live in production yet.

The webhook registration steps provided here are not live in production for Shipium Beta customers of this service. Your Shipium contact will notify you when these user interface components are available in the Shipium Partner Console. In the interim, please work directly with your Shipium contact to manage your webhook.

Once in the Shipium Partner Console, follow these instructions to register your organization's webhook:

  1. In the navigation pane at left, navigate to Tracking, and then Webhooks.
  1. 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 Webhooks screen, as the test webhooks appear in the sample screenshot below. If your organization has no existing registered webhooks, this screen will contain no webhooks until you've registered your first one.
  1. Complete the required Settings fields shown in the Add 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 tracking event notifications. This is the endpoint deployed on your server to receive incoming webhook tracking 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 tracking updates for all tenants, only one tenant, or a subset of tenants. This field allows you to determine how to set up automatic tracking 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 tracking 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.
  1. Next , select the tracking events you’d like to receive automatic tracking event update notifications for. If you choose to customize your selections rather than opting to Send me all event types, use the Tracking event types for your webhooks section below to help determine your selections.
  1. 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 tracking event notifications to your organization's server.
  1. Finally, send a test payload to your endpoint. 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 tracking events will push to your designated endpoint as received once you've completed registration.

Tracking event types for your webhook

The following table maps example carrier delivery steps and messages to the designated tracking event type rollup categories for webhooks: Info Received, In Transit, Out For Delivery, Delivered, Exception, and Unknown.

Tracking Event Type for WebhookExample Carrier Delivery StepMessage
Info ReceivedInfo ReceivedInformation about this package has been received by the carrier.
RegisteredNot ApplicableThe package has been registered for tracking.
In TransitPicked UpThe package has been picked up by the carrier.
In TransitArrived Carrier FacilityThe package has arrived at a carrier facility.
In TransitDeparted Carrier FacilityThe package has left the carrier facility.
In TransitIn TransitThe package is in transit to the customer.
Out For DeliveryOut For DeliveryThe package is out for delivery.
DeliveredDeliveredThe package has been delivered.
ExceptionHoldThe package is on hold and in possession of the carrier.
ExceptionExceptionThere has been a carrier exception for this package.
UnknownUnknownTracking ID for the package is unknown to the carrier.

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 tracking 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.

Sample webhook messages

This section provides sample expected webhook messages as they would appear when delivering tracking event updates, for both the standard model and the Tracking Updated event type.

Sample webhook message for standard model

This sample JavaScript Object Notation (JSON) message demonstrates the standard model of the push event sent to your organization's endpoint for your registered webhook.

{
  "events": [ // List of events to potentially support notifying in batch
      {
          "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 
          }
      }
  ]
}

Sample webhook message for eventType tracking_updated

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

{
    "events": [
        {
            "metadata": {
                "eventId": "ddc5a651-214f-409a-a86c-fb04070570dd",
                "eventTimestamp": "2022-10-07T12:38:36Z",
                "eventType": "tracking_updated",
                "payloadSchemaVersion": "v1",
                "testEvent": false
            },
            "payload": {
                "trackings": [
                  {
                    "shipiumTrackingId": "c4179ccb-b894-42e7-b532-5f02fb196010",
                    "carrierId": "ups",
                    "carrierTrackingId": "1Z074E600397684456",
                    "carrierServiceMethodId": "ups-ground-service-method",
                    "shipmentStatus": "Delivered",
                    "shippedDateTime": "2022-05-19T04:22:47Z",
                    "deliveredAtDateTime": "2022-05-23T19:41:05Z",
                    "carrierEstimatedDeliveryDate": null,
                    "trackingEvents": [
                        {
                            "carrierDescription": "Delivered",
                            "shipmentStatus": "Delivered",
                            "eventDate": "2022-05-23T19:41:05Z",
                            "postalCode": "45133",
                            "country": "US",
                            "city": "HILLSBORO",
                            "region": "OH"
                        },
                        {
                            "carrierDescription": "Departed from Facility",
                            "shipmentStatus": "In Transit",
                            "eventDate": "2022-05-21T07:13:00Z",
                            "postalCode": null,
                            "country": "US",
                            "city": "Columbus",
                            "region": "OH"
                        },
                        {
                            "carrierDescription": "Arrived at Facility",
                            "shipmentStatus": "In Transit",
                            "eventDate": "2022-05-20T21:40:00Z",
                            "postalCode": null,
                            "country": "US",
                            "city": "Columbus",
                            "region": "OH"
                        },
                        {
                            "carrierDescription": "Shipper created a label, UPS has not received the package yet.",
                            "shipmentStatus": "In Transit",
                            "eventDate": "2022-05-19T04:22:47Z",
                            "postalCode": null,
                            "country": "US",
                            "city": null,
                            "region": null
                        }
                    ]
                  }
                ]
            }
        }
    ]
}

Updated 7 months ago

What’s Next

To use the Shipium Carrier Tracking Search API rather than the webhook tracking capability, visit the Carrier Tracking Search API page.