Track parcels with Notifications Webhook

Notifications Webhook provides a way to receive notifications triggered from events that relate to the delivery of your parcels. Find out more about Notifications Webhook in Metapack Help Centre.

Prerequisites

In order to receive notifications about the delivery of your parcels, you need to have a Notifications Webhook configured in your Metapack Delivery Manager account.

How to track parcels activity with Notifications Webhook

To track parcels activity with Notifications Webhook, you need to provide the information related to your parcels to Metapack Tracking API by means of DeliveryLeg (Note: this is optional when you ship your parcels with Metapack).

This information will then be used by Notifications Webhook to send you rich notifications regarding the delivery of your parcels.

Example of a DeliveryLeg with the parcel information for which you want to receive notifications:

Copy

Copied

{
  "trackingIdentifier": "REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
  "carrierCode": "HER_UK",
  "order":{
    "orderRef": "REPLACE-WITH-YOUR-ORDER-REFERENCE"
  },
  "delivery": {
    "type": "PUDO",
    "deliveryWindow": {
      "from": "2023-06-13T13:00:00.000Z",
      "to": "2023-06-13T14:00:00.000Z"
    }
  },
  "recipient": {
    "countryCode": "GBR",
    "timeZone": "Europe/London",
    "contact": {
      "name": "John Doe",
      "email": "johndoe@email.com",
      "phone": "07814354765"
    }
  },
  "sender": {
    "countryCode": "GBR",
    "timeZone": "Europe/London"
  }
}

Example of a trigger event that originates from a carrier, a store or a PUDO location:

Copy

Copied

{
  "trackingIdentifier": "REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
  "eventCode": "AWAITING_COLLECTION_FROM_PICKUP_POINT",
  "eventDate": "2023-06-13T13:36:29.043Z",
  "eventTimeZone": "Europe/London",
  "eventLocation": {
    "address": {
      "city": "London",
      "countryCode": "GBR",
      "postCode": "WC1X 8XZ",
      "stateProvince": "London"
    },
    "location": {
      "latitude": 51.52325226913702,
      "longitude": -0.1146692876584629,
      "name": "Warehouse 11"
    }
  },
  "deliveryWindow": {
    "from": "2023-06-13T13:00:00.000Z",
    "to": "2023-06-13T14:00:00.000Z"
  }
}

Example of the notification sent to a configured webhook endpoint for the given parcel and trigger event:

Copy

Copied

{
  "httpMethod": "POST",
  "headers": {
    "User-Agent": "Metapack Webhook Notification",
    "Content-Type": "application/json",
    "Content-Language": "en-GB",
    "{YOUR-SECURITY-HEADER}": "{YOUR-SECRURITY-TOKEN}"
  },
  "body": {
    "trackingIdentifier": "REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
    "eventCode": "AWAITING_COLLECTION_FROM_PICKUP_POINT",
    "eventDate": "2023-06-13T13:36:29.043Z",
    "eventTimeZone": "Europe/London",
    "orderRef": "REPLACE-WITH-YOUR-ORDER-REFERENCE",
    "recipientEmail": "johndoe@email.com",
    "recipientName": "John Doe",
    "recipientPhone": "07814354765",
    "recipientCountryCode": "GBR",
    "senderCountryCode": "GBR",
    "deliveryType": "PUDO",
    "deliveryWindow": {
      "from": "2023-06-13T13:00:00.000Z",
      "to": "2023-06-13T14:00:00.000Z",
      "hasChanged": false
    },
    "carrierDisplayName": "Evri",
    "eventDescription": "Ready to collect",
    "statusCode": "READY_TO_COLLECT",
    "statusDescription": "Ready to collect",
    "eventCategory": "HAPPY",
    "eventLocation": {
      "address": {
        "city": "London",
        "countryCode": "GBR",
        "postCode": "WC1X 8XZ",
        "stateProvince": "London"
      },
      "location": {
        "latitude": 51.52325226913702,
        "longitude": -0.1146692876584629,
        "name": "Warehouse 11"
      }
    }
  }
}

Notification triggers

A notification for a known parcel is triggered the first time one of the following events occurs:

IN_TRANSIT
COLLECT_AT_LOCAL_PO
OUT_FOR_DELIVERY
CUSTOMER_CARDED
CUSTOMER_TO_COLLECT_FROM_CARRIER
DELIVERED
DELIVERED_TO_PO_BOX
DELIVERED_TO_NEIGHBOUR
DELIVERED_SPECIFIED_SAFE_PLACE
PARCEL_COLLECTED_FROM_PICKUP_POINT
AWAITING_COLLECTION_FROM_PICKUP_POINT
DELIVERED_TO_LOCKER_COLLECTION_POINT
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION
ATTEMPTED_DELIVERY
ATTEMPTED_DELIVERY_2ND
ATTEMPTED_DELIVERY_3RD
PARCEL_DAMAGED
NO_ACCESS_TO_RECIPIENTS_ADDRESS
ROUTING_ERROR
ADDRESS_QUERY
DELAYED_NOT_CARRIER
CARRIER_DELAYS
CUSTOMER_CARDED
PARCEL_LOST
CUSTOMER_MOVED
NOT_DELIVERED

Sending a notification once for a given trigger event is intended to prevent sending multiple times the same communication to your customers and reduce the volume of notifications sent to your webhook endpoint.

Refer to Supported tracking events for more information about these events.

Notification schema

The notification sent by Notifications Webhook is a HTTP POST request that includes the following information:

Mandated HTTP headers:

User-Agent : "Metapack Webhook Notification" - Identifies the agent calling the webhook endpoint.
Content-Type : "application/json" - Defines the content type of the body containing the notification payload.
Content-Language : "en-GB" - Defines the language of the notification payload.

Optional HTTP header:

{YOUR-SECURITY-HEADER} : {YOUR-SECURITY-TOKEN} for authentication purposes.

HTTP body containing the notification payload as a JSON object that contains the following properties:

Copy

Copied

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "trackingIdentifier": {
      "type": "string",
      "description": "The external identifier used to track the parcel."
    },
    "eventCode": {
      "type": "string",
      "description": "Metapack event code.",
      "enum": [
        "IN_TRANSIT",
        "COLLECT_AT_LOCAL_PO",
        "OUT_FOR_DELIVERY",
        "CUSTOMER_CARDED",
        "CUSTOMER_TO_COLLECT_FROM_CARRIER",
        "DELIVERED",
        "DELIVERED_TO_PO_BOX",
        "DELIVERED_TO_NEIGHBOUR",
        "DELIVERED_SPECIFIED_SAFE_PLACE",
        "PARCEL_COLLECTED_FROM_PICKUP_POINT",
        "AWAITING_COLLECTION_FROM_PICKUP_POINT",
        "DELIVERED_TO_LOCKER_COLLECTION_POINT",
        "DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION",
        "ATTEMPTED_DELIVERY",
        "ATTEMPTED_DELIVERY_2ND",
        "ATTEMPTED_DELIVERY_3RD",
        "PARCEL_DAMAGED",
        "NO_ACCESS_TO_RECIPIENTS_ADDRESS",
        "ROUTING_ERROR",
        "ADDRESS_QUERY",
        "DELAYED_NOT_CARRIER",
        "CARRIER_DELAYS",
        "CUSTOMER_CARDED",
        "PARCEL_LOST",
        "CUSTOMER_MOVED",
        "NOT_DELIVERED"
      ]
    },
    "eventDate": {
      "type": "string",
      "description": "Date and time when the event occured.",
      "format": "date-time"
    },
    "eventTimeZone": {
      "type": "string",
      "description": "Time zone at the location of the event."
    },
    "orderRef": {
      "type": "string",
      "description": "The reference of the order."
    },
    "recipientEmail": {
      "type": "string",
      "description": "Recipient email address.",
      "format": "email"
    },
    "recipientName": {
      "type": "string",
      "description": "Recipient name."
    },
    "recipientPhone": {
      "type": "string",
      "description": "Recipient mobile number."
    },
    "recipientCountryCode": {
      "type": "string",
      "description": "The country code of the recipient address in ISO 3166-1 alpha-3 format in UPPERCASE."
    },
    "senderCountryCode": {
      "type": "string",
      "description": "The country code of the sender address in ISO 3166-1 alpha-3 format in UPPERCASE."
    },
    "deliveryType": {
      "type": "string",
      "description": " delivery channel, which supports home delivery, pickup point, and collection in store.",
      "enum": ["HOME","PUDO","STORE"]
    },
    "deliveryWindow": {
      "type": "object",
      "description": "The window in which to expect the delivery of the parcel.",
      "properties": {
        "from": {
          "type": "string",
          "description": "The earliest date when the parcel is expected to be delivered.",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "description": "The latest date when the parcel is expected to be delivered.",
          "format": "date-time"
        },
        "hasChanged": {
          "type": "boolean",
          "description": "Delivery window data changed from its previous value"
        }
      },
      "required": [
        "from",
        "to"
      ]
    },
    "carrierDisplayName": {
      "type": "string",
      "description": "The carrier name displayed to a shopper."
    },
    "eventDescription": {
      "type": "string",
      "description": "Description of the event according to the event code."
    },
    "statusCode": {
      "type": "string",
      "description": "The stage of a parcel journey when the event occurred.",
      "enum": [
        "IN_TRANSIT",
        "OUT_FOR_DELIVERY",
        "DELIVERED",
        "READY_TO_COLLECT",
        "COLLECTED"
      ]
    },
    "statusDescription": {
      "type": "string",
      "description": "User friendly description of the status code."
    },
    "eventCategory": {
      "type": "string",
      "description": "Grouping of different events that have the same behaviour or will in future drive the same treatment in products.",
      "enum": ["HAPPY", "EXCEPTION_ACTION", "EXCEPTION_INFO"]
    },
    "exceptionMessage": {
      "type": "string",
      "description": "The shopper-facing headline and body text that positions the nature of the exception, states the impact of the exception, and provides a call to action for the shopper (if applicable)."
    },
    "eventLocation": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "The city (or town) of an address."
            },
            "countryCode": {
              "type": "string",
              "description": "The country code of an address in ISO 3166-1 alpha-3 format in UPPERCASE."
            },
            "postCode": {
              "type": "string",
              "description": "The postal code of an address."
            },
            "stateProvince": {
              "type": "string",
              "description": "The region or province of an address."
            }
          }
        },
        "location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number",
              "description": "The distance of a place north or south of the equator, measured in degrees."
            },
            "longitude": {
              "type": "number",
              "description": "The distance of a place east or west of the Greenwich meridian, measured in degrees."
            },
            "name": {
              "type": "string",
              "description": "Name of place."
            }
          }
        }
      }
    }
  },
  "required": [
    "trackingIdentifier",
    "eventCode",
    "eventDate",
    "eventTimeZone"
  ]
}

Notification retry strategy

Notifications Webhook will retry to send the notification in case of failure from the targeted webhook endpoint. The retry strategy is as follows:

Up to 6 retries over 3 hours with a 30 minutes interval between each retry.