Event Driven Tracking (webhooks)

Send an email to api@wineshipping.com to enable your event-driven feed and bespoke samples of tracking events for your account

Setup

You provide the webhook URL and we will send event driven data to the provided URL via HTTP POST method in the JSON format described here.

Event types

Available events include the following; we can configure your event feed to include all or a subset of these event types. The "tag" field in the posted event data indicates the event type:

Pending: New tracking number that are pending to track with last-mile carrier
InfoReceived: New tracking number, the last-mile carrier has received the request and is about to pick up the shipment.
InTransit: The shipment is on its way, has left the warehouse
OutForDelivery: Carrier is about to deliver the shipment , or it is ready to pickup.
AttemptFail: Carrier attempted to deliver but failed, and usually leaves a notice and will try to deliver again.
Delivered: The shipment was delivered successfully.
AvailableForPickup: The package arrived at a pickup point near the recipient and is available for pickup.
Exception: Hold, undelivered, returned shipment to sender or any shipping exceptions.
Expired: Shipment has no tracking information for 30 days since added.

Retries

In case of an unsuccessful event when calling your URL (HTTP response code NOT between 200 and 299), Wineshipping attempts to deliver your webhooks for up to 14 times with an exponential back off by this formula: 2^(number of retry) x 30s; as shown:

Num of attempt	Num of retry	Delay (sec) before send out	Accumulated Delay (sec)
1	0	0	0
2	1	30	30
3	2	60	90
4	3	120	210
5	4	240	450
6	5	480	930
7	6	960	1890
8	7	1920	3810
9	8	3840	7650
10	9	7680	15330
11	10	15360	30690
12	11	30720	61410
13	12	61440	122850
14	13	122880	245730

For example:

If the first attempt fails, we will retry the 2nd attempt 30s later.
If the 7th attempts fail, we retry the 8th attempt 960s later
If the 14th attempts fail, we will not send out that webhook any more.

Event Data

Event data will be posted to your URL in JSON format illustrated in the example below:

{
  "event": "tracking_update",
  "event_id": "555e9daa-f6ca-48a2-b30c-48e23cd0d0d6",
  "is_tracking_first_tag": true,
  "msg": {
    "active": true,
    "aftership_estimated_delivery_date": {
      "estimated_delivery_date": "2023-07-22",
      "confidence_score": null,
      "estimated_delivery_date_min": "2023-07-22",
      "estimated_delivery_date_max": "2023-07-23"
    },
    "android": [],
    "checkpoints": [
      {
        "checkpoint_time": "2023-07-20T15:00:15-05:00",
        "city": null,
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-20T20:00:16+00:00",
        "location": "US, United States",
        "message": "Shipment Ready for UPS",
        "raw_tag": "MP",
        "slug": "ups",
        "state": null,
        "subtag": "InfoReceived_001",
        "subtag_message": "Info Received",
        "tag": "InfoReceived",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-20T15:00:15-05:00",
        "city": null,
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-20T20:12:01+00:00",
        "location": "United States",
        "message": "Updated Delivery Time",
        "raw_tag": "UT",
        "slug": "ups",
        "state": null,
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-20T19:20:01-05:00",
        "city": "Earth City",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-21T00:20:56+00:00",
        "location": "Earth City, MO, US, United States",
        "message": "On the Way",
        "raw_tag": "OR",
        "slug": "ups",
        "state": "MO",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-20T19:20:01-05:00",
        "city": null,
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-21T00:35:25+00:00",
        "location": "United States",
        "message": "Updated Delivery Date",
        "raw_tag": "UP",
        "slug": "ups",
        "state": null,
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-20T22:09:00-05:00",
        "city": "Earth City",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-21T03:20:46+00:00",
        "location": "Earth City, MO, US, United States",
        "message": "On the Way",
        "raw_tag": "DP",
        "slug": "ups",
        "state": "MO",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-21T14:59:00-04:00",
        "city": "Orlando",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-21T19:16:38+00:00",
        "location": "Orlando, FL, US, United States",
        "message": "On the Way",
        "raw_tag": "AR",
        "slug": "ups",
        "state": "FL",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-21T23:04:00-04:00",
        "city": "Orlando",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T03:19:39+00:00",
        "location": "Orlando, FL, US, United States",
        "message": "On the Way",
        "raw_tag": "DP",
        "slug": "ups",
        "state": "FL",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-22T00:50:00-04:00",
        "city": "Clearwater",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T05:05:31+00:00",
        "location": "Clearwater, FL, US, United States",
        "message": "On the Way",
        "raw_tag": "AR",
        "slug": "ups",
        "state": "FL",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-22T05:18:16-04:00",
        "city": "Clearwater",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T09:19:53+00:00",
        "location": "Clearwater, FL, US, United States",
        "message": "Preparing for Delivery",
        "raw_tag": "YP",
        "slug": "ups",
        "state": "FL",
        "subtag": "InTransit_001",
        "subtag_message": "In Transit",
        "tag": "InTransit",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-22T10:11:07-04:00",
        "city": "Clearwater",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T14:11:17+00:00",
        "location": "Clearwater, FL, US, United States",
        "message": "Out for Delivery",
        "raw_tag": "OT",
        "slug": "ups",
        "state": "FL",
        "subtag": "OutForDelivery_001",
        "subtag_message": "Out for Delivery",
        "tag": "OutForDelivery",
        "zip": null
      },
      {
        "checkpoint_time": "2023-07-22T11:06:54-04:00",
        "city": "BELLEAIR",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T15:08:24+00:00",
        "location": "BELLEAIR, FL, 33756, US, United States",
        "message": "Delivery Attempted",
        "raw_tag": "48",
        "slug": "ups",
        "state": "FL",
        "subtag": "AttemptFail_001",
        "subtag_message": "Failed Attempt",
        "tag": "AttemptFail",
        "zip": "33756"
      },
      {
        "checkpoint_time": "2023-07-22T11:08:44-04:00",
        "city": "BELLEAIR",
        "coordinates": [],
        "country_iso3": "USA",
        "country_name": "United States",
        "created_at": "2023-07-22T15:10:23+00:00",
        "location": "BELLEAIR, FL, 33756, US, United States",
        "message": "Delivered",
        "raw_tag": "KB",
        "slug": "ups",
        "state": "FL",
        "subtag": "Delivered_001",
        "subtag_message": "Delivered",
        "tag": "Delivered",
        "zip": "33756"
      }
    ],
    "courier_connection_id": null,
    "courier_destination_country_iso3": "USA",
    "courier_redirect_link": "https://www.ups.com/track?loc=en_US&tracknum=1Z59E877A871526000&requester=WT/trackdetails",
    "courier_tracking_link": "https://www.ups.com/track?loc=en_US&tracknum=1Z59E877A871526000&requester=WT/trackdetails",
    "created_at": "2023-07-20T16:22:03+00:00",
    "custom_estimated_delivery_date": null,
    "custom_fields": {
      "contents": "1xI0001003686(EACH) | 2xZ1883530252(750) | 1xZ2081643956(750) | 2xZ2266944449(750) | 6xZ2477531880(750) | 1xZ2512530726(750)",
      "contents_collateral_units": "1",
      "contents_merch_units": "0",
      "contents_product_units": "12",
      "date_dc": "07/18/2023 16:35:31",
      "date_input": "2023-07-18",
      "dc_cid": "CONT-013922021",
      "dc_oid": "14039199",
      "dc_pool": "DAILY",
      "dc_ship_confirm": "2023-07-20T22:54:40+00:00",
      "dc_ver": "v3",
      "final_mile": "ups",
      "oms_contents": "1xI0001003686(EACH) | 2xZ1883530252(750) | 1xZ2081643956(750) | 2xZ2266944449(750) | 6xZ2477531880(750) | 1xZ2512530726(750)",
      "regulatory_attributes": "FL:123456789",
      "rsd": "2023-07-19",
      "seller_name": "The Winery Name",
      "seller_number": "10000",
      "shipfrom_dc": "ETC01",
      "special_attributes": "icepack",
      "transmission_id": "OiHTFObyOOasdd",
      "transport_zone": "5",
      "tref": "f6c39d42-4afe-4957-9ad3-ea099d492b7c"
    },

    "custom_fields": {
      "container_type_code": "750STNDUP12BTL",
      "contents": "1xF09351(750) | 1xI200OFF-1223(EACH) | 1xI2309WIQ4COUP(EACH) | 1xI2309WITY(EACH) | 1xI24WIMRG-04(EACH) | 1xN01425(750) | 1xN01436(750) | 1xN01457(750) | 2xN01512(750) | 1xN01519(750) | 1xR10555(750) | 1xR10576(750) | 1xR10608(750) | 2xW21651857(750)",
      "contents_collateral_units": "4",
      "contents_merch_units": "0",
      "contents_product_units": "12",
      "date_packed": "2024-04-23T00:23:41+00:00",
      "dc_carrier": "FEX-GRND",
      "dc_oid": "17892793",
      "dc_pool": "DAILY",
      "dc_ship_confirm": "2024-04-23T00:57:38+00:00",
      "dc_ver": "v3",
      "final_mile": "fedex",
      "oms_contents": "1xF09351(750) | 1xI200OFF-1223(EACH) | 1xI2309WIQ4COUP(EACH) | 1xI2309WITY(EACH) | 1xI24WIMRG-04(EACH) | 1xN01425(750) | 1xN01436(750) | 1xN01457(750) | 2xN01512(750) | 1xN01519(750) | 1xR10555(750) | 1xR10576(750) | 1xR10608(750) | 2xW21651857(750)",
      "regulatory_attributes": "",
      "rsd": "2024-04-22",
      "seller_name": "The Winery Name",
      "seller_number": "10000",
      "shipfrom_dc": "VCX01",
      "special_attributes": "hold.location",
      "special_instructions": "",
      "transmission_id": "c15b079f-a1e5-4c4b-9ac1-3db3b4fb7555",
      "transport_zone": "5",
      "tref": "a8da0749-c6ad-4bbd-bf62-acaa2d814555"
    },
    "customer_name": "Jane D.",
    "delivery_time": 3,
    "delivery_type": null,
    "destination_city": "Belleair",
    "destination_country_iso3": "USA",
    "destination_postal_code": "33756-1925",
    "destination_raw_location": "555 Main Street, Belleair, FL, 33756-1925",
    "destination_state": "FL",
    "emails": ["jane@email.com"],
    "expected_delivery": "2023-07-24",
    "first_attempted_at": "2023-07-22T11:06:54-04:00",
    "first_estimated_delivery": {
      "datetime": "2023-07-24",
      "datetime_max": null,
      "datetime_min": null,
      "source": "Carrier EDD",
      "type": "specific"
    },
    "id": "rwfu4vriciwerlkbd1g0y00j",
    "ios": [],
    "language": "en",
    "last_mile_tracking_supported": true,
    "last_updated_at": "2023-07-22T15:10:23+00:00",
    "latest_estimated_delivery": {
      "source": "Carrier EDD",
      "datetime": "2023-07-24",
      "type": "specific",
      "datetime_min": null,
      "datetime_max": null
    },
    "next_couriers": [],
    "note": null,
    "on_time_difference": -2,
    "on_time_status": "early",
    "order_date": "2023-07-18T16:35:31-07:00",
    "order_id": "CONT-013922021",
    "order_id_path": null,
    "order_number": "33516482",
    "order_promised_delivery_date": null,
    "order_tags": [],
    "origin_city": "Earth City",
    "origin_country_iso3": "USA",
    "origin_postal_code": "630451224",
    "origin_raw_location": "Earth City, Missouri",
    "origin_state": "Missouri",
    "path": "deprecated",
    "pickup_location": null,
    "pickup_note": null,
    "return_to_sender": false,
    "shipment_delivery_date": "2023-07-22T11:08:44-04:00",
    "shipment_package_count": null,
    "shipment_pickup_date": "2023-07-20T15:00:15-05:00",
    "shipment_tags": [],
    "shipment_type": "UPS Ground",
    "shipment_weight": 34.6,
    "shipment_weight_unit": "lb",
    "signed_by": null,
    "slug": "ups",
    "smses": ["+18555072501"],
    "source": "api",
    "subscribed_smses": ["+18555072509", "+18555072501"],
    "subscribed_emails": ["jane@email.com", "another_email@email.com"],
    "subtag": "Delivered_001",
    "subtag_message": "Delivered",
    "tag": "Delivered",
    "title": "33516482",
    "tracked_count": 19,
    "tracking_account_number": null,
    "tracking_destination_country": "USA",
    "tracking_key": null,
    "tracking_number": "1Z59E877A871526000",
    "tracking_origin_country": "USA",
    "tracking_postal_code": "33756-1925",
    "tracking_ship_date": "20230720",
    "tracking_state": "FL",
    "unique_token": "deprecated",
    "updated_at": "2023-07-22T15:10:23+00:00"
  },
  "ts": 1690038623
}

Note: date and times provided by carriers vary in precision by event. Format may be:

YYYY-MM-DD
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SS+TIMEZONE

Event Driven Tracking (webhooks)

Setup

Event types

Retries

Event Data

More Schema Documentation

Was this helpful?