MANAGE WEBHOOKS
![](/api/content/dam/fedex-com/irc/common/Create.png)
Introduction
Webhook is a software architecture method to automate push notifications that occur between sender and receiver applications whenever a new event happens.
Webhook is described as a user-defined HTTPS callbacks (typically POST request) triggered by change in status of a specific event. It sends near real-time automated notifications (messages/information/data) from sender (server-side) application to receiver (client-side) application based on the "Event Reaction" concept (i.e., don’t contact me, I will only contact you if I have something new for you).
API vs Webhook Workflow
Below pictorial representation describes how the event data is received in case of API request and with the Webhook.
![Logo](/api/content/dam/fedex-com/irc/businessdocimages/TWFig1.png)
Overview
FedEx Tracking Webhook aids in improving overall shipment lifecycle fulfillment experience. The FedEx E-commerce customers can now get near real-time visibility on the shipment events through secure tracking event push notifications.
Tracking Webhook Features and Benefits
FedEx Tracking Webhooks provides significant competitive advantages as below:
- Modernized technology solution with self-serve capability.
- User-friendly interface with a webhook management console to provide customer(s) with the ability to manage Tracking Webhooks on their own.
- Tracking Webhooks are FedEx account-based subscriptions.
- Receive near real-time tracking event(s) notifications for the shipment(s) while adding value to your customer’s post shopping cart experience.
- Get up-to-date tracking event data with estimated delivery date (EDD) and estimated delivery time window (EDTW).
FedEx Developer Portal Roles:
Within the FDP, you can perform specific functions based on the configured role.
To learn more about FedEx Developer Portal, refer to the Organization Administration Guide.
Business Rules and Best Practices
- One shipping account number cannot be used in multiple webhooks.
- Only FDP users with the administrator role can access, manage, and use Tracking Webhook capabilities and documentation.
- At least one available shipping account number must be selected in order to create a Tracking Webhook.
- The destination URL/endpoint created by the customer must:
- Be of HTTPs host.
- Respond to POST requests and parse JSON payloads.
- Be of HTTPs host.
- 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:
Dev/Beta Prod 169.63.102.107
150.239.111.98
169.59.163.56
169.63.176.128
150.239.215.211
150.239.210.140
Sandbox Console
Status
![](/api/content/dam/fedex-com/irc/common/Success_1x.png)
Success
Test webhook tracking event details delivered successfully
![](/api/content/dam/fedex-com/irc/common/Error_1x.png)
Error
Test webhook tracking event details delivery failed
- Fail-over Mechanism when Webhooks fails to work, customers will have to rely on EDI feed and/or Track API polling requests to get the missed event updates during outages and failures.
- 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 FDP:
- User/Customer cannot delete the account(s):
- If it is associated with any webhook.
Note: Any webhook includes all in-progress/failed/active/paused Tracking Webhook. - If the account is available or associated with a project, and
- 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.
- If it is associated with any webhook.
- User/customer can delete the account(s):
- The account must belong to the same organization.
- User/Customer must be an admin to delete accounts from the organization.
- User/Customer cannot delete the account(s):
Common Constraints
- All customer shipments associated with the account numbers of operating companies- FedEx Express®, FedEx Ground®, FedEx Freight® and FedEx Ground® Economy (formerly known as FedEx SmartPost®) are in scope irrespective of destination or origin (inbound, outbound, international, domestic, etc.).
- Webhooks only supports enterprise 9-digit FedEx freight account numbers.
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 a LTL to enterprise account. - FedEx Office, FDC, FedEx Custom Critical® operating companies are out of scope.
- 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/Pause/Resume/Cancel/Delete) on the subscribed Tracking Webhooks.
- Translations:
- Tracking payload translations are supported in 41 languages (locales).
Click here to view the list of supported languages. - Email notification translation is available for languages supported by U.S. region only. (Locale: en-US, es-US)
- Tracking payload translations are supported in 41 languages (locales).
Note: All above statements are subject to change when future updates are released.
Test Webhook URL
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 Tracking 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 Tracking Webhook/click on WEBHOOK in FILTERS -> Tracking Webhook card:
- -> Overview -> Documentation button -> in Sandbox Console, click on Try this Webhook.
- -> Docs -> in Sandbox Console, click on Try this Webhook
Steps:
Following are the steps to use Test Webhook URL functionality:
- Click on Test Webhook URL button.
- Fill out 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 Tracking Webhook response.
- Token value must be between minimum length of 25 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)
- French (Canada)
- Chinese (China)
- German (Germany)
- Japanese (Japan)
- Spanish (Mexico)
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).
- Event-Specific Tracking Response (Response type consists of secured tracking data with only the most recent event information).
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
- Proof of Delivery
- Estimated Delivery
Status Event
A tracking event in the packages’ lifecycle. Select one of the tracking events to be received. Following are the available sample status events:
- Shipment information sent to FedEx (Label Created)
- Picked up
- In transit
- Item Held at Delivery Office
- Out for delivery
- Delivered
- Picture Proof of Delivery
- Signature Proof of Delivery
- Estimated Delivery Date (EDD)
- Estimated Delivery Time Window (EDTW)
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
- Shipment information sent to FedEx (Label Created)
- Picked up
In-Transit
- In transit
- Item held at delivery office
Delivery
- Out for delivery
- Delivered
Proof of Delivery
- Picture Proof of Delivery
- Signature Proof of Delivery
Estimated Delivery
- Estimated Delivery Date (EDD)
- Estimated Delivery Time Window (EDTW)
- Check the FedEx Developer Portal License Agreement (FDPLA) box to Sign/Accept the License Agreement.
- 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.
- 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
Webhook Validation Process
To create a Tracking Webhook, the webhook URL needs to be validated first. You will need to complete this validation process before you can finish creating your webhook project (or to later edit or resume a webhook project). This process ensures that we know to whom and where we are sending data, and it also ensures that you know the origin of the data we send you.
- Create a destination URL and security token. (This must be done outside of FDP)
- Create a destination URL to receive FedEx authentication codes/messages and Tracking Webhook payload notifications.
- Generate a security token that can be used as a secret key to authenticate and validate information transmitted between you (customer) and FedEx.
- Security token requirements:
- A minimum length of 25 characters and a maximum length of 100 characters.
- 1 upper case character
- 1 lower case character
- 1 numeric character
Example:Y1F6OiVUQW2JPSElmRE9U0IY5
- Security token requirements:
- Set up the process that will be used to validate your URL and verify the connection.
- Use a HMAC_SHA256 algorithm to create a challenge string response with a request body (challenge string that FedEx will send you upon webhook creation) and a security token.
- Go through the “Create webhook project” process within the developer portal FDP.
- During the process of creating your webhook project – which is outlined in detail in the “Create a Tracking Webhook project” section – enter the destination URL and security token you created in step 1.
- FedEx will then send you a challenge string that you can use to create a challenge string response.
Example: {"challengeString": "91f93d94ee3f4215a21f684ac9be9aad"}
Note: This workflow process also applies for editing and resuming a webhook project.
- Use a HMAC_SHA256 algorithm to hash the request body with the security token to generate a challenge string response.
- You will use this challenge string response in the next step.
Example: HMAC_SHA256 (challenge string, security token) = challengeStringResponse
- You will use this challenge string response in the next step.
- Send the HTTP status code, the challenge string, and your challenge string response to complete validation.
- To complete the validation process, you must send three items together in the response body:
- An HTTP status code: 200 or 202
- 200 means OK
- 202 means accepted
- The challenge string that FedEx sent you in step 4.
- The challenge string response that you generated in step 5.
Example: {"challengeString": "91f93d94ee3f4215a21f684ac9be9aad", "challengeStringResponse": "d74b04bdb41e52aa7b7c39d84ee82d4843b0f016864231409470912e80ceb17b}
- When you respond with these items, include “challengeString” and “challengeStringResponse” in the response body.
Note: The expected time frame for your response is within 3 seconds. If you respond with an HTTP status code other than 200 or 202, then the validation process will fail, and respective error code and error message will be displayed.
- An HTTP status code: 200 or 202
- To complete the validation process, you must send three items together in the response body:
- After the response is received, the challenge string and challenge string response will be validated by comparing it with the challenge string and challenge string response generated by FedEx.
- If FedEx successfully validates these items, then your webhook project will be created, and you will receive a confirmation message.
Example: <<Webhook project name>> successfully created. Changes may take up to 10 minutes to go into effect.
- If FedEx successfully validates these items, then your webhook project will be created, and you will receive a confirmation message.
What is MAC/HMAC and how is it used in the validation process?
FedEx uses HMAC to validate your URL whenever you are creating, editing, or resuming any Tracking Webhook project.
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 Tracking Webhook will use HMAC SHA256.
Example (of a pseudocode snippet to illustrate an HMAC SHA256 hashing):
- First, initialize MAC using HmacSHA256 algorithm and the security token as the secret key.
- Then, finalize the MAC operation by hex encoding the request payload sent by FedEx.
- This final hash should match with the value of the header x-fedex-signature in the PUSH sent by FedEx.
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secureToken.getBytes(), "HmacSHA256"));
return new String(Hex.encode(mac.doFinal(payLoad.getBytes())));
Note: The secretKey used is the secureToken provided by the customer when setting up the Webhook or when testing the Webhook URL.
How Tracking Webhook Works
The Tracking 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). You can create a Tracking Webhook project to access this functionality.
Create Tracking Webhook
You can create a Tracking Webhook to push near real-time secured tracking event data to the destination URL for shipments associated with one/multiple FedEx account number(s).
Creation of a Tracking Webhook is a four-step process:
- Step 1: Configure Project
- Step 2: Enter Project Details
- Step 3: Choose Shipping Accounts
- Step 4: Confirm Details and Accept Terms
Navigation:
Following are the ways to navigate to Tracking Webhook page:
- My Projects (on the left Navigation Panel) -> Webhooks tab -> +CREATE A WEBHOOK PROJECT
- API Catalog (on the left Navigation Panel) -> search for Tracking Webhooks/click on WEBHOOK in FILTERS -> Tracking Webhook card:
- -> Overview -> Documentation button -> +CREATE A WEBHOOK PROJECT
- -> DOCS -> +CREATE A WEBHOOK PROJECT
Steps:
Following are the steps for creating Tracking Webhook :
- Click on +CREATE A WEBHOOK PROJECT button.
- On the pop-up window, select one of the below options from the dropdown menu to specify the type of company for which you need webhook access.
- Ships with FedEx and needs to integrate FedEx webhooks into their system.
- Sells or provides a software solution that uses FedEx data and is not a certified FedEx Compatible provider.
Note: Currently, the FedEx Tracking Webhook solution is not available for this option. - Is a certified FedEx Compatible provider.
Note: Currently, the FedEx Tracking Webhook solution is not available for this option. As a member of the FedEx Compatible program, if you want to access Track API or other FedEx integration solutions, please reach out to your channel manager. If you do not know who your channel manager is, contact your company administrator.
- On the Configure Webhook page:
- a. 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).
Note: To check the pricing related information for the webhook projects, refer to the Tracking webhook overview page. - Select the features you need and click on Next.
Note: To know more about the features, click on the help icon (?) next to the feature.
Features Description 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 photo showing the exact location of their package once it is delivered to their doorstep.
- 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.
Estimated delivery
This feature helps recipients plan their schedules by providing a date and/or time range for shipment deliveries. This includes:
- Estimated delivery date (EDD)
- Estimated delivery time window (EDTW)
Tracking Events
Select one event category to receive email notifications when tracking events occur. Following are the tracking events:
- Ship
- In-Transit
- Delivery
- Exceptions
- Custom delivery options
Event-based filtering
Includes inbound, outbound, or third-party shipments in your webhook response.
- a. 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).
- On the Enter Details page, enter the following fields:
Field Name Description Webhook Project Name
This is non-empty, unique Webhook project name and should not be repeated in any other Webhooks.
- The Webhook project name is auto populated with a suggested name which can be edited as required.
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, don’t include fedex.com or its sub domains in the URL).
- Customer can repeat destination URL in multiple Webhooks.
To learn more about destination URL and webhook security, refer to the business rules and best practices section.
Security Token
Used as shared secret to authenticate and validate Tracking Webhook response.
- Token value must be between minimum length of 25 characters and maximum of 100 characters.
- At least 1 uppercase, 1 lowercase and 1 numeric character are required.
- Customer can repeat the security token in multiple Webhooks.
- Security Token will be used to create Hash-based Message Authentication Code (HMAC) signature for response validation.
Payload Language (Country)
Select the preferred language for tracking data translation from the drop-down list.
Tracking Type
Select the type of response in which tracking data needs to be received.
- Detailed Tracking: This tracking type consists of secured tracking data with entire history of events.
- Event-Specific Tracking: This tracking type consists of secured tracking data with only the most recent event information.
Email address
Provide one Email address(es).
Email language (country)
Select preferred Language for receiving email notifications.
Note:- Email notification translations is available for languages supported by U.S. regions only. (Locale: en-US, es-US)
- On the Choose Shipping Accounts page, select the accounts you would like to associate with the webhook project.
Note:- Only the accounts that are not associated with any other webhooks will be displayed in the list.
- You need to associate minimum one account to the project to proceed to the next step.
- A maximum of 100 accounts can be associated with a single webhook project using the webhook UI. You can add more accounts using the webhooks API. To get access to webhook API, contact FedEx customer support or help desk.
- On the Confirm details page, check the details of the webhook project, check and accept the terms and conditions, and select Create to create the webhook project.
The successful request submission will create a new Tracking Webhook with a system generated Webhook ID and will have an Active status.
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:
- FedEx will push a Challenge token.
- Webhook Destination URL upon receipt of the challenge token should respond with 200 (OK) or 202 (ACCEPTED) as HTTP status code to FedEx.
- When a Webhook is created successfully, customer will receive a confirmation message.
Sample Confirmation Message: <<Webhook name>> successfully created. Changes my 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.
- FedEx will display respective error code and error message.
Sample Error Message: Challenge string response does not match.
Error Code: <<error code>>
![Error_message Error_message](/api/content/dam/fedex-com/irc/businessdocimages/Error%20message.png)
Managing Tracking Webhooks
The management console is available on FedEx developer portal for managing Tracking Webhooks. The console provides you with the options to edit, delete, pause, and resume the active/paused Tracking 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, Webhook Id and FedEx shipping Account Number.
- Any changes (SAVED/CREATED/EDITED/RESUBMITTED/PAUSED/RESUMED) made to a Tracking Webhook could take up to 10 minutes to get into effect.
- ACTIVE Tracking Webhook(s) will stay active indefinitely unless:
- The webhook is PAUSED or CANCELLED.
- If the customer requests aligned Technical Consultant to pause the Tracking Webhook(s).
- View details option is available only for ACTIVE and PAUSED Webhooks.
- FAILED and PAUSED Tracking Webhook(s) will be available in Webhook Management Console for 30 days only.
- If no action (EDIT/RESUME/DELETE) is taken within 30 days, the paused Tracking Webhook(s) will get automatically cancelled.
- If no action (EDIT and RESUBMIT/DELETE) is taken within 30 days, the failed Tracking 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 Tracking 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 Tracking Webhook.
Steps:
Follow below steps for Editing a Webhook:
- Select My Projects on the left Navigation Panel.
- Select Webhooks tab.
- Select Individual Webhook listed under My Webhooks.
- Select Edit action from the kebab menu (⋮) on the respective Tracking Webhook.
- On the Configure Webhook page:
- 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).
- Select the features you need and click on Next.
Note: To know more about the features, click on the help icon (?) next to the feature.
- On the Enter Details page, select the field(s) you would like to edit and select Next.
- On the Choose shipping accounts page, add or remove the accounts associated with the webhook and select Next.
- 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:
- The successful Webhook URL validation results in the following response to be triggered:
- A Challenge token will be pushed to Destination URL provided while creating a Webhook.
- Destination URL upon receipt of the challenge token should respond back with 200 (OK) or 202 (ACCEPTED) as HTTP status code along with challenge token to FedEx.
- When the changes are updated successfully, you should receive a confirmation message.
Sample Confirmation Message: <<Webhook name>> is successfully updated. Changes my 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).
- Enter the new security token to proceed with resubmitting the Edit request
- FedEx will display respective error code and error message.
Sample Error Message: Please provide the correct destination URL.
Error Code: <<error code>>
Note:
- Webhook ID associated with an existing Tracking Webhook remains un-changed when a customer edits/updates the Webhook(s).
- It will take 10 minutes for the updated changes of an existing Tracking Webhook to get into effect.
- If you click on cancel during the edit Tracking Webhook workflow, the edit workflow will be aborted, and you will be navigated back to the previous page (Webhook Management Console page).
- When an account is associated to a Tracking Webhook(s) then, FedEx will push events happening for new shipments created thereafter for that account.
- When an account is dissociated from a Tracking Webhook(s) then, FedEx will push all the already matched or in-flight shipments data and will not push any data for new shipments created thereafter.
View Webhook Details
You can use this option to view details/configurations of an existing Tracking webhook.
Steps:
Follow below steps to view the Webhook details page:
- Select My Projects on the left Navigation Panel.
- Select Webhooks tab.
- Select Individual Webhook listed under My Webhooks.
- Select View Details action from the kebab menu (⋮) on the respective Tracking Webhook.
View Details page consists of below content:
- Webhook Name
- Three action buttons based on the status of the webhook are:
- Edit Webhook
- Pause/Resume Webhook
- Cancel Webhook
- Webhook project details tab: Consists of below fields and its respective values:
- Billing Details
- Project status
- Billing account number
- Project Details
- Project Name
- Destination URL
- Webhook ID
- Payload language
- Tracking type
- Email address
- Email language
- Features selected
- Retry policy
- Proof of delivery
- Estimated delivery
- Tracking events
- Event based filtering
- Webhook based Shipping account numbers.
- Billing Details
- Webhook project history details tab:
This tab shows the details of the actions performed for the respective webhook such as time when the webhook was Paused, edited etc.
Pause Webhook
You can use option to pause a webhook if you do not wish to receive tracking data temporarily.
Steps:
Follow below steps for pausing a Webhook:
- Select My Projects on the left Navigation Panel.
- Select Webhooks tab.
- Select Individual Webhook listed under My Webhooks.
- Select Pause action from the kebab menu (⋮) on the respective Webhook.
- Enter the reason for pausing the webhook in the REASON FOR PAUSE text box.
- Click PAUSE to submit the request.
Response:
- When a Webhook is paused successfully, you will receive a confirmation message.
Sample Confirmation Message:
<<Webhook Name>> is successfully paused. FedEx will stop pushing shipments event data from hereafter. Changes may take up to 10 minutes to go into effect.
- When a Webhook fails to pause, you will receive respective error code and an error message.
Sample Error Message: We are unable to process your request at the moment. Please try again later.
Error Code: <<error code>>
Limitations:
- All paused Webhook(s) will be available in the “Webhooks” Management Console for 30 days only.
- If no action (EDIT/RESUME/CANCEL) is taken within 30 days, the paused Webhook(s) will get automatically deleted.
Note:
- When a Webhook is paused, FedEx will not push the already matched or in-flight shipment event data and new shipments event data created thereafter.
Resume Webhook
You can use this option, if a Webhook needs to be resumed or made Active again.
Steps:
Follow below steps for Resuming a Webhook:
- Select “My Projects” on the left Navigation Panel.
- Select “Webhooks” tab
- Select Individual Webhook listed under My Webhooks.
- Select Resume action from the kebab menu (⋮) on the respective paused Webhook.
- Enter the reason for resuming the webhook in the REASON FOR RESUME text box.
- Click RESUME to submit the request.
Note:
- You can resume a paused Webhook(s) within 30 days.
- When a Webhook is resumed then FedEx will push new event data for already matched or in-flight shipments and new shipments created thereafter.
Validation:
- Webhook Name should be unique.
- Webhooks URL must be in Standardized Syntactical format.
- All the Webhook required fields must not be empty.
- At least one available account number should remain selected for resuming a Webhook.
- Successful Validation:
- FedEx will push a Challenge token.
- Webhook Destination URL upon receipt of the challenge token should respond with 200 (OK) or 202 (ACCEPTED) as HTTP status code along with challenge token to FedEx.
- When the Webhook is resumed successfully, customer will receive a confirmation message.
Sample Confirmation Message:
<<Webhook Name>> is successfully resumed. FedEx will start pushing shipment event data from hereafter. Changes may take up to 10 minutes to go into effect.
- Unsuccessful/Failed validation:
- If FedEx receives any other response other than 200 (Ok) or 202 (Accepted), then the validation of the Webhook destination URL will be considered as failed.
- Customer will receive an error code and 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:
- Select My Projects on the left Navigation Panel.
- Select Webhooks tab.
- Select Individual Webhook listed under My Webhooks.
- Select Delete action from the kebab menu (⋮) on the respective Webhook.
- 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>>
Note:
- Deleted Webhook(s) cannot be recovered.
- When a customer deletes an active/paused Webhook then FedEx will not push the already matched or in-flight shipments event data, or any new shipments event data created thereafter.
Cancel Webhook
If an active or paused Webhook is no longer needed, use this option to cancel it.
Steps:
Follow below steps for cancelling a Webhook:
- Select My Projects on the left Navigation Panel.
- Select Webhooks tab.
- Select Individual Webhook listed under My Webhooks.
- Select CANCEL action from the kebab menu (⋮) on the respective Webhook.
- 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>>
Note:
- Cancelled Webhook(s) cannot be recovered. The cancelled webhook will still be visible in the webhook management page for 90 days. You can only view the details of a cancelled webhook. After 90 days, the webhook will be automatically deleted.
- When a customer cancels an active/paused Webhook then FedEx will not push the already matched or in-flight shipments event data, or any new shipments event data created thereafter.
Searching Webhook
You can search Webhooks based on Webhook Name, Destination URL, Webhook 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/Paused/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.
- Edit and Resubmit
Limitations
- FAILED Tracking 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 Tracking Webhook(s) will get automatically deleted.
Administrator role Tracking Webhook capabilities:
Following are the Webhook capabilities available for an Administrator:
- Test Webhook URL
- Create Webhooks
- Save Webhooks
- View Details of Webhook
- Edit/Update Webhooks
- Pause/Resume Webhooks
- Cancel Webhook
- Delete Webhooks
- Search/Sort/Filter Webhooks
- Add contributor and viewer role members to the project.
Webhook Feature Details
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 at span of 6 hours time.
if FedEx does not receive a successful response in the predefined time span, then FedEx will stop redelivery of that specific event.
For more information on retry policies, refer to the Retry/Redelivery mechanism section.
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 and 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).
- 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.
To learn more about certain use cases for the SPOD and PPOD with the corresponding tracking events, refer to the SPOD and PPOD use cases.
Estimated Delivery
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: 20th Nov 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 6pm.
Tracking Events
This feature allows customers to track the status of their shipments by sending them email notifications. 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 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.
- Custom delivery options: Select this option to receive notification for some personalized tracking events. Example: hold at location request accepted etc.
For more information on the available shipment event options, refer to the Webhooks tracking events table.
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.
Disable/Re-Enable a Tracking Webhook Capability on FDP
DISABLE:
- If you want to disable the Tracking Webhook Capability temporarily or permanently, you can contact your aligned Technical Consultant and raise a request to disable the Tracking Webhook Capability.
- After having Tracking Webhook Capability disabled, you will not be able to access and view any functionalities and documentation related to Tracking Webhooks on the FDP.
RE-ENABLE:
Within 30 days:
- If you want to enable the Tracking Webhook Capability within 30 days, you need to contact your aligned Technical Consultant and raise a request to re-enable the Tracking Webhook Capability.
- After having tracking Webhook capability re-enabled, you will re-gain access to all functionalities and documentation related to Tracking Webhooks in the FDP.
- By default, all the associated Webhooks under the organization will be in “PAUSED” status. You will need to manually change the status of one by one to “ACTIVE” to start receiving track event updates.
- If no action is taken within 30 days for PAUSED, FAILED, or SAVED tracking webhooks, then the paused webhook(s) will get automatically cancelled, and the failed or saved webhook(s) will get automatically deleted.
After 30 days:
- If you want to enable the Tracking Webhook Capability after 30 days, you need to contact your aligned Technical Consultant and raise a request to re-enable the Tracking Webhook Capability.
- After having Tracking Webhook Capability re-enabled, you will re-gain access to all functionalities and documentation related to Tracking Webhooks in the FDP.
- By default, all the associated Webhooks under the organization are deleted permanently. It’s like Webhook capability is enabled for first-time user, you can go ahead and start creating now.
Note: You will receive enabled/disabled email notification, whenever Tracking Webhook capability is re-enabled or disabled respectively for your respective organization.
Monitoring Failures and Retry Mechanism
You will need to monitor the failures on your end internally and reach out/notify to your aligned Technical Consultant if failures persist.
Retry limitations:
- Retry/Redelivery 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. These retry/redelivery attempts are made over a span of 6 hours.
- Each time FedEx tries to deliver the event data and receives anything other than 200 or 202, then that transaction will be considered as a failure.
- FedEx will continue to push new event(s) data if they happen while retrying for the original event and any subsequent events happening thereafter for that Webhook.
Retry/Redelivery logic
A total of four redelivery attempts to deliver a shipment event notification will be attempted over a span of six hours from the occurrence of the first retry attempt of the event.
![retry_logic](/api/content/dam/fedex-com/irc/businessdocimages/New%20retry%20policy%20webhook.png)
- Retry logic:
- Attempt 1:
Example: Tracking number 823497234824 is 'Delivered', WMT 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
Note: Retry Attempts 2, 3 and 4 are eligible for every failed redelivery attempt.
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.
- Attempt 1:
- Redelivery attempts:
- Redelivery attempt 1: Occurs after 30 mins of attempt 1. If it fails, then 3 retries will be attempted. If retry attempts also fail, then mechanism moves to redelivery attempt 2.
- Redelivery attempt 2: Occurs after 60 mins of attempt 1. If it fails, then 3 retries will be attempted. If retry attempts also fail, then mechanism moves to redelivery attempt 3.
- Redelivery attempt 3: Occurs after 3 hours of attempt 1. If it fails, then 3 retries will be attempted. If retry attempts also fail, then mechanism moves to redelivery attempt 4.
- Redelivery attempt 4: Occurs after 6 hours of attempt 1. If it fails, then 3 retries will be attempted. If retry attempts also fail, then the event is considered as missed event.
Note:
- After 4 Redelivery attempts, if FedEx does not receive a successful response, then FedEx will stop redelivery of that specific event.
- Once, the connection is re-established within 6 hours, then FedEx will try to redeliver all the failed events (failed to deliver within retry/redelivery mechanism) again.
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 as 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.
Automatic Pausing (Disable Logic)
If the total number of unsuccessful redelivery attempts have exceeded the defined retry queue limit, then the respective webhook will be paused. FedEx will send an email to inform you that the webhook has been paused due to multiple unsuccessful attempts and that you should check your destination URL.
The total number of unsuccessful attempts permitted in a retry queue is 10,000. If the number of unsuccessful attempts exceeds this limit, then the respective webhook will be paused and an email notification will be sent to the webhook subscribers to inform the same and that they should check their network/server connectivity.
Note: If a webhook is paused, then the customer will not receive any event notifications for any shipment until you resume the webhook manually for your organization profile.
The below flowchart depicts the autopause logic:
Use cases for Signature Proof of Delivery (SPOD) and Picture Proof of Delivery (PPOD)
Use Case | Tracking Event | SPOD/PPOD | Result |
---|---|---|---|
Use Case 1 |
Delivery |
Selected |
You will receive two delivery timestamps:
Note
|
Use Case 1.1 |
Delivery |
Not Selected |
You will receive only the “Delivery” event timestamp when the package is delivered.
|
Use Case 2 |
Ship/In-Transit/Exceptions |
Selected |
You will receive only one delivery timestamp for the SPOD/PPOD event, which will contain the delivery timestamp along with the SPOD/PPOD image byte array. If SPOD/PPOD is not selected, then you will not receive any delivery timestamp information. Note
|
Use Case 2.1 |
Ship/In-Transit/Exceptions |
Not Selected |
You will not receive any delivery timestamp information. Note: You will not receive webhook notifications for any delivery of packages with and without SPOD/PPOD also. |
Response