Customer Benefits:

• Improve recipient confidence with proactive notifications for in-transit changes to Estimated Delivery Date and day of delivery Time Window.
• Reduce customer service costs for WISMO (Where Is My Order) calls as well as delivery disputes by providing FedEx Picture Proof of Delivery.
• Enhance customer experience by providing near real time notifications on shipment status.
• Gain operational efficiencies by receiving real time push update on shipments, instead of polling continuously to check for track updates on every shipment.

Features and Tracking Events

Tracking Events

This feature allows to track the status of shipments proactively notify customers on different updates in the shipment lifecycle. It provides the customers with options to choose the exact stage of the shipment process/events they wish to receive a notification/alert for. The available shipping events are:

• Ship: This option provides notification when the selected shipment event occurs. Example: Label Created, Pickup, etc.
• In transit: This option provides notification for the shipment transit events. Example: In transit, item held at delivery office, etc.
• Delivery: This option provides notification for the shipment delivery events. Example: out for delivery, delivered, etc.
• Exceptions: This option provides notification for the delivery exceptions. Example: clearance delay, etc.
• Convenient delivery options: Select this option to receive notification for some personalized tracking events. Example: hold at location request accepted.

For more information on the available shipment event options, refer to the Status Codes and Statuses for Webhook Tracking Events table.

Proof of Delivery

This feature is used to acknowledge an order has successfully arrived at its intended destination. This includes:

• Picture proof of delivery (PPOD): PPOD allows customers to receive a picture of the exact location of their package once it is delivered to their doorstep.
  Webhooks delivers the PPOD images in the JSON payload in a base64 format. The images can then be converted to a JPEG format.
  

  Note:

  • PPOD is available in the U.S., Canada, Puerto Rico, Hong Kong, New Zealand, United Kingdom, and Ireland.
  • PPOD is only available for FedEx Ground, FedEx Express and residential packages/address(es).
  • PPOD is available for eligible deliveries when SPOD is not required. PPOD and SPOD are not available together.
  • PPOD is available for on-signature required (NSR) deliveries that are not given directly to a customer (e.g. handed directly to a customer during delivery).
  • PPOD supports image size from 14000 to 33000 bytes (Applicable for 320 x 240 resolution image).

   

• Picture proof of delivery attempt (PPODA): PPODA allows customers to receive a picture of the exact location of where the package is to be delivered, in the event that delivery cannot be completed. Webhooks delivers the PPODA images in the JSON payload in a base64 format. The images can then be converted to a JPEG format.
  • PPODA is available in the U.S. and Puerto Rico.
  • PPODA is only available for FedEx Ground, FedEx Express and residential and commercial packages/address(es).
  • PPODA Image can be:
  1. PPODA image photo of Doortag on Door.
  2. Photo of Obstruction to Delivery Point (i.e., locked gate).
  3. PPOD Image of Packages Delivered at the stop.
  • PPODA supports image size from 14000 to 33000 bytes (Applicable for 320 x 240 resolution)

 

• Signature proof of delivery (SPOD): SPOD allows customers to receive an image of the recipient’s signature as well as their name delivery date, time and location. The SPOD information will be presented as a byte array instead of an image. The byte array is a base64 encoded string, which should be decoded to get the final signature image in PNG format
  • SPOD is not available for Tracking Number based Webhook.
  • The SPOD image size will be from 4000 to 6000 bytes (Applicable for 400x95 resolution image).
  • The SPOD image size will be from 5000 to 8000 bytes (Applicable for 230x150 resolution image).

 

• GPS proof of delivery (GPSPOD):
  • GPS POD allows customers to receive the geographical coordinates of the delivery location.
    

    Note: GPSPOD is available by default for account number based webhook subscription.

Estimated Delivery Date and Delivery Time Window Events

This feature helps recipients of the shipments plan their schedules by providing a date and/or time range for shipment deliveries. This includes:

• Estimated delivery date (EDD): This option provides an estimated date of delivery of the shipment to the recipient. Example: Nov, 20, 20XX.
• Estimated delivery time window (EDTW): This option provides the recipient with an estimated time window for the shipment delivery on the day of actual delivery. Example: 2pm to 6pme.

Event Based Filtering

This feature allows customers to organize their webhook projects based on the billing methods for the shipments. The options are:

• Inbound: select this option for shipments that will be delivered to you and will be paid for, by you as the recipient.
• Outbound: select this option for shipments that will be shipped by you and will be paid for, by you as the sender.
• Third-party: select this option for inbound and outbound shipments that are billed to you as a third-party payer.

Note: Your FedEx account number will be used to bill or pay for the shipments. For third-party payer, you may not be the shipper or recipient, but the charges will be billed to your FedEx account number.

Retry Policy

This feature prevents FedEx from sending tracking event data in the event of a client-side issue. FedEx will hold the data and attempt to resend it within a span of 3 retries within 5 minutes intervals.

If FedEx does not receive a successful response in the defined time span, then FedEx will stop redelivery of that specific event. However, customer can request for missed events over a period of last 7 days through a manual "RETRY" button on the Webhook project Details page.

For more information on retry policies, refer to the Retry mechanism section.

• One shipping account number cannot be used in multiple webhooks.
• The destination URL/endpoint created by the customer must:
  
  • Be of HTTPs host.
    
  • Respond to POST requests and parse JSON payloads.
  • Character limit to 200 characters
  • Your URL will be blocked if it includes:
    • RFC1918 IP space
    • fedex.com or any of its subdomains
    • IP addresses in the URL (including localhost, 127.0.0.1)

• Webhook Security: Only HTTPS connections using TLS (SSL) 1.2 or higher protocol versions that is configured with a certificate from a valid certificate authority (CA) is supported. Whitelist the below IP addresses to receive updates from FedEx servers without any interruptions:
  

  Prod
  Clients can whitelist: “nat.fxconnect.eastus2.heap-prod.fedex.io”
  Using CIDR "20.65.16.22/31"

• Customers may sometimes receive the tracking event updates out of order and must look at the scan event time stamp for the correct order.
• Deleting Account(s) in FedEx Developer Portal:
  • User/Customer cannot delete the account(s):
    1. If it is associated with any active webhook.
       
    2. If the account is available or associated with a project, and
    3. If it is the only account in a project/webhook.
       
       Note: User/Customer needs to remove the account from the project/webhook first and then delete it from the organization.
  • User/customer can delete the account(s):
    1. The account must belong to the same organization.
    2. User/Customer must be an admin to delete accounts from the organization.

Common Constraints

• All customer shipments associated with the FedEx 9-digit account numbers of operating companies- FedEx Express®, FedEx Ground® and FedEx Ground® Economy (formerly known as FedEx SmartPost®) are in scope irrespective of destination or origin (inbound, outbound, international, domestic, etc.).
• Webhook only supports 9-digit enterprise/parcel enabled accounts. Enterprise accounts enable the creation of shipments associated with all FedEx operating companies including FedEx Express and FedEx Ground.


Note: 9-digit LTL freight only accounts are not supported, if you want to add LTL freight account, then you must reach out to customer support to port an LTL to enterprise account.
• Customers must manage the order of the shipment tracking events received on their end.
• Automated email notifications are sent whenever there is any activity (Saved/Failed/Create/Update/Cancel/Delete) on the subscribed Shipment Visibility Webhooks.
• Translations:
  • Tracking payload translations are supported in 41 languages (locales).(Coming Soon)
    Click here to view the list of supported languages.
  • Currently tracking payload translation is supported in English (United States).
  • Email notification translations is available for languages supported by U.S. regions only. (Locale: en-US, es-US)

FedEx Developer Portal User roles:

Within the FedEx Developer Portal, you can perform specific functions based on the configured role.
To learn more about FedEx Developer Portal, refer to the Organization Administration Guide.

You can use the Test Webhook URL feature to test the type of tracking data returned to the Destination URL (receiver/listener server). This helps to validate the URL and data returned prior to creating a Webhook.

Navigation:

Following are the ways to navigate to Test Webhook URL Sandbox Console:

• My Projects (on the left Navigation Panel) -> Webhooks tab -> Test Webhook URL button->in Sandbox Console, click on Try this Webhook
• API Catalog (on the left Navigation Panel) -> search for Webhook/click on WEBHOOK in FILTERS -> Shipment Visibility Webhook card:
  1. -> Overview -> Documentation button -> in Sandbox Console, click on Try this Webhook.
  2. -> Docs -> in Sandbox Console, click on Try this Webhook.

Steps:

Following are the steps to use Test Webhook URL functionality:

1. Click on Test Webhook URL button.
2. Enter the following Test parameters:

   Field Name	Description
   Destination URL	This is the URL to receive the Tracking event data/payload. Customer should provide a working and valid destination URL. Destination URL provided must be in the standardized syntactical format (secure https URL).
   Security Token	Used as shared secret to authenticate and validate Shipment Visibility Webhook response. Token value must be between minimum length of 26 characters and maximum of 100 characters. At least 1 uppercase, 1 lowercase and 1 numeric character are required. Security Token will be used to create Hash-based Message Authentication Code (HMAC) signature for response validation.
   Payload language	Select the preferred language for tracking data translation from the drop-down list. Following are the available 6 sample languages: English (United States)(Default)
   Tracking Type	Select type of response in which tracking data needs to be received. Detailed Tracking Response (Response type consists of secured tracking data with entire history of events).(Default) Event-Specific Tracking Response (Response type consists of secured tracking data with only the most recent event information).(Coming soon)
   Tracking events	Select one higher-level category to receive email notifications related to shipment events in the package lifecycle. Following are the higher-level categories: Ship In Transit Delivery Exceptions Estimated Delivery
   Status Event	A tracking event in the packages’ lifecycle. Select one of the tracking events to be received. Following are the available 10 sample status events: Picked up In transit Delivered Delivery Exception

    

   Note: “Status Event” field values will be populated based on the selected "Tracking Event Category”. Refer the following table to learn more about the “Tracking Event Category” and their respective “Status Events”.
   
   

    

   Status Event Category	Status Event
   Ship	Picked up
   In-Transit	In transit
   Delivery	Delivered
   Exceptions	Delivery Exception
   Estimated Delivery(Coming Soon)	Estimated Delivery Date (EDD) Estimated Delivery Time Window (EDTW)

    

3. Check the FedEx Developer Portal License Agreement (FDPLA) box to Sign/Accept the License Agreement.
4. Click the PUSH button to view test results.

Response :

Following are the response parameters in the Sandbox:

• Body – The body contains the response parameters in the Test Webhook URL tab within Sandbox Console.
• Status – This section in Test Results tab provides you the status of the request that is processed.

Sample Success Message:
Success
Test Webhook tracking event details delivered successfully.

If test event delivery fails, the STATUS will be displayed as Error in Test Results tab with respective error code and error message.

Sample Error Message:
Error Code:<<error code>>
Test Webhook tracking event details delivery failed.

Validation Rules:

• Webhook URL must be in Standardized Syntactical format.
• All the required fields for testing a Webhook URL must not be empty.
• For Successful Validation:
  • FedEx will send a request with sample event JSON.
  Note: Webhook destination URL should respond with 200 (OK) as HTTP status code to FedEx.
• For Unsuccessful/Failed Validation:
  • If FedEx receives any response other than 200 (OK), then the validation of the Webhook destination URL will be considered as failed.
  • FedEx will display the error code and error message in Test Results tab

What is a MAC/HMAC and how is it used in the validation process?

A message authentication code (MAC) provides a way to check the integrity of information transmitted over or stored in an unreliable medium, based on a secret key. Typically, MACs are used between two parties that share a secret key to validate information transmitted between the two parties.

A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, e.g., SHA256, in combination with a secret shared key. HMAC is specified in RFC 2104. FedEx Shipment Visibility Webhook will use HMAC SHA256.

SHA256( security token + payload) =  Base 64 encoded fdx-signature as part of payload Header

Validation Rules:

• Webhook Name should be unique.
• Webhooks Destination URL must be in Standardized Syntactical format.
• All the required fields for creating a Webhook must not be empty.
• At least one available FedEx shipping account number should be associated for creating a Webhook.
• For Successful validation:
  • When a Webhook is created successfully, customer will receive a confirmation message.

    Sample Confirmation Message: <<Webhook name>> successfully created. Changes may take up to 10 minutes to go into effect.

• For Unsuccessful/Failed validation:
  • If FedEx receives any response other than 200 (OK) or 202 (Accepted), then the validation of the Webhook destination URL will be considered as failed.

The Shipment Visibility Webhook allows FedEx to push near real-time secured tracking event data to a destination URL for shipments associated with a specific FedEx account number(s).

Create Shipment Visibility Webhook

You can create a Shipment Visibility Webhook project on FedEx Developer Portal and then associate the webhook either to one or more FedEx account numbers or FedEx tracking numbers based on your selected subscription type. Navigate to the top of the page and select the desired webhook subscription type tab: Account Number based or Tracking Number based, to view the steps to create the respective webhook.

The management console is available on the FDP for managing the Shipment Visibility Webhooks. The console provides you with the options to edit,retry and cancel the active Webhooks as required.

Navigation:

Following is the way to navigate to MANAGE WEBHOOKS (Webhooks Management Console) page:

• My Projects (on the left Navigation Panel) -> Webhooks tab -> MANAGE WEBHOOKS page

Common Limitations:

• Customer must always provide a secure https destination URL in standardized syntactical format and be validated as a working event receiver.
• FedEx will push Tacking Event data to customer’s destination URL in a standardized JSON format in the selected language (locale).
• Unique Fields that cannot be repeated in multiple Webhooks: Webhook Name, Subscription Id and FedEx shipping account number.
• Any changes (SAVED/CREATED/EDITED/RESUBMIT) made to a Webhook could take up to 10 minutes to get into effect.
• ACTIVE Webhook(s) will stay active indefinitely unless:
  • The webhook is CANCELLED.
• View details option is available only for ACTIVE webhooks.
• FAILED Webhook(s) will be available in Webhook Management Console for 30 days only.
  • If no action (EDIT and RESUBMIT/DELETE) is taken within 30 days, the failed Webhook(s) will get automatically deleted.
• Any saved for later webhooks will be shown as IN-PROGRESS in Webhook Management Console for 90 days only.
  • If no actions (continue creating or delete) is taken within 90 days, the in-progress Webhook(s) will get automatically deleted.

Edit Webhook

You can use this option to add, update or remove information/details in field(s) of an existing Webhook.

Steps:

Follow below steps for Editing a Webhook:

1. Select My Projects on the left Navigation Panel.
2. Select Webhooks tab.
3. Select Individual Webhook listed under My Webhooks.
4. Select Edit action from the kebab menu (⋮) on the respective Shipment Visibility Webhook.
5. On the Configure Webhook page:
   1. Check the default billing account number displayed for your organization. If you want to change the billing account number, click on ADD BILLING ACCOUNT TO YOUR ORGANIZATION (if you have a single billing account) or SELECT ANOTHER BILLING ACCOUNT (this option is displayed if you have multiple billing accounts under your organization).
   2. Select the features you need and click on Next.
      
      Note: To learn more about the features, click on the help icon (?) next to the feature.
6. On the Enter Details page, select the field(s) you would like to edit and select Next.
7. For account number based webhook subscription, on the Choose shipping accounts page, add or remove the accounts associated with the webhook and select Next.
8. On the Confirm details page, check the changes made in the webhook project and select Next to confirm.

The successful request submission will update the Webhook, and it will remain in ACTIVE status.

Validation Rules:

• When the changes are updated successfully, you should receive a confirmation message.

  Sample Confirmation Message: <<Webhook name>> is successfully updated. Changes may take up to 10 minutes to go into effect.

• The unsuccessful/failed Validation:
  • Validation to the destination URL is considered as failed if, FedEx receives responses other than 200 (OK) or 202 (Accepted).

View Webhook Details

You can use this option to view details/configurations of an existing Shipment Visibility webhook.

Steps:

Follow below steps to view a Webhook:

1. Select My Projects on the left Navigation Panel.
2. Select Webhooks tab.
3. Select Individual Webhook listed under My Webhooks.
4. Select View Details action from the kebab menu (⋮) on the respective Shipment Visibility Webhook.

Below table represents the view details page for the selected subscription type.

Cancel Webhook

If an active Webhook is no longer needed, use this option to cancel it.

Steps:

Follow below steps for cancelling a Webhook:

1. Select My Projects on the left Navigation Panel.
2. Select Webhooks tab.
3. Select Individual Webhook listed under My Webhooks.
4. Select CANCEL action from the kebab menu (⋮) on the respective Webhook.
5. You can cancel the Webhook in the Edit screen using CANCEL button.

Response:

• When a Webhook is cancelled successfully, you will receive a confirmation message.

  Sample Confirmation Message: <<Webhook Name>> is successfully cancelled. 

• When a Webhook is not cancelled successfully, you will receive an error message.

  Sample Error Message: We are unable to process your request at the moment. Please try again later.

  Error Code: <<error code>>

Delete Webhook

If a saved or failed Webhook is no longer needed, use this option to delete it.

Steps:

Follow below steps for Deleting a Webhook:

1. Select My Projects on the left Navigation Panel.
2. Select Webhooks tab.
3. Select Individual Webhook listed under My Webhooks.
4. Select Delete action from the kebab menu (⋮) on the respective Webhook.
5. You can delete the Webhook in the Edit screen using DELETE button.

Response:

• When a Webhook is deleted successfully, you will receive a confirmation message.

  Sample Confirmation Message: <<Webhook Name>> is successfully deleted. 

• When a Webhook is not deleted successfully, you will receive an error message.

  Sample Error Message: We are unable to process your request at the moment. Please try again later.

  Error Code: <<error code>>

Searching Webhook

You can search Webhooks based on Webhook Name, Destination URL, Subscription ID and Account Number.

Sorting Webhook

You can sort the Webhooks in ascending or descending order based on Webhook Name, Last Modified (date) and Status columns for better visibility.

Filtering Webhook

• You can filter webhooks based on the single status (Active/Processing/Failed) or multiple statuses selection of the webhook.
• You can clear the filter selection by clicking on "CLEAR ALL" button.

Processing Webhook

•  When a webhook create or edit request(s) takes more than 6 seconds then the status will be set to "PROCESSING".
• ·Webhook(s) in "PROCESSING" status are in disabled state. In this state you cannot perform any action.
• ·When a webhook status is set to "PROCESSING", the following message is displayed: "Your request for [Webhook project name] is still in progress, check back to see when it is complete."

Failed Webhook

• When a webhook create request(s) in “PROCESSING” status fails to create then the status will be set to "FAILED".
• When a webhook(s) is in "FAILED" status, you can perform only below two actions:
  • Edit and Resubmit
    Using this action, you can edit & submit the failed subscription (either you can submit the request as it is or can edit the details and submit the request again).
  • Delete
    Using this action, you can delete the existing failed webhook.

Limitations

• FAILED Webhook(s) will be available in Webhook Management Console for 30 days only.
• If no action (EDIT and RESUBMIT/DELETE) is taken within 30 days, the failed Webhook(s) will get automatically deleted.

You will need to monitor the failures on your end internally and notify FedEx Helpdesk if failures persist.

Retry limitations:

• Retry Mechanism (retry to push event data) occurs only when FedEx does not receive 200 or 202 HTTP status code in response from the destination URL. The retry attempts are made over a span of 15 minutes at 5-minute intervals 3 times over 15 minutes (see retry diagram).
• Each time FedEx tries to deliver the event data and receives anything other than 200 or 202, then that transaction will be considered a failure.
• Every event in the case of a failure will be retried 3 times over 15 minutes with 5-minute intervals in between each retry. If all of those retries fail, then the event will be pushed to a missed events queue which you can retrieve from using the retry mechanism on your webhooks project. All failed events that have the following HTTPS series values will be stored for 7 days and can be retrieved by initiating the retry process on your Webhook project:
  • 200 - Null
  • 400 - ClientID does not match
  • 401- Data Works token is not valid
  • 500 – Null
  Any missed events in those 7 days will be sent to the subscribed destination URL

Retry logic:

Every event in the case of a failure will be retried 3 times over 15 minutes with 5-minute intervals in between each retry. If after all of those retries fail, then the event will be pushed to a missed events queue which you can retrieve from using the retry mechanism on your webhooks project.

• Retry logic:
  • Attempt 1:
    Example: Tracking number 823497234824 is 'Delivered', Client sent 400 response. (Anything other than HTTP status 200/202 is considered failure). In this case, we call attempt 1 as failure.
    • Attempt 2 - 1min +/ jitter - Retry 1
    • Attempt 3 - 2min +/ jitter - Retry 2
    • Attempt 4 - 4min +/ jitter - Retry 3

    If FedEx receives a successful response like an HTTP status 200 & 202 for any of the retry requests, then FedEx will stop the retry mechanism for a given event.

Important Points to Note:

• Retry Mechanism (retry to push event data) occurs only when FedEx does not receive 200 or 202 HTTP status code in response from the destination URL.
• Each time FedEx tries to deliver the event data and receives anything other than 200 or 202, then that transaction will be considered a failure.
• FedEx will continue to push new event(s) data if they happen while retrying for the original event.
• FedEx will also push for subsequent events happening thereafter for that Webhook.

• To learn more about the production keys (API and secret key), refer to API Authorization documentation page.
• To learn more about how to get started with FedEx APIs, refer the Getting Started guide .
• To learn more about FedEx project roles, refer the Organization Administration Guide.
• To learn more about pricing refer to Shipment Visibility Webhook Overview .