FedEx tracking webhooks provide near-real-time shipment updates throughout the shipment lifecycle.

Unlike tracking APIs, which require applications to request shipment status, webhooks automatically deliver shipment updates as new information becomes available.

This guide covers:

• Three integration principles
• How webhooks work
• Processing webhook payloads
• Customer notifications
• Timestamps
• Best practices and common integration issues

Successful webhook integrations follow three principles.

Treat every webhook payload as a shipment state update

Do not assume every payload represents a new tracking milestone. FedEx publishes a new payload whenever new shipment information becomes available.

A payload may contain:

• A new tracking event
• Updated delivery predictions
• Proof-of-delivery information
• Recipient information
• Other shipment data changes

Multiple payloads can share the same tracking milestone while containing different shipment information.

Store and merge shipment data

Each payload may contain new or updated shipment information. Store each webhook payload and merge new information into the existing shipment record.

Do not overwrite the existing shipment record with the latest payload. Instead, preserve previously received shipment data and incorporate new information to maintain a complete, up-to-date shipment record throughout the shipment lifecycle.

Use business rules to drive actions

Use business rules to determine when to update systems or notify customers.

Do not trigger actions solely from an event code. Before updating customer-facing applications or sending notifications, evaluate:

• Tracking milestones
• Shipment availability
• Notification timing
• Business requirements

Recommended processing model

The following diagram illustrates how the three webhook integration principles work together in a typical implementation. Every webhook payload is processed as a shipment state update, merged into a centralized shipment record, and evaluated through business rules before applications are updated or customer notifications are sent.

Important: Multiple webhook payloads can be generated for the same tracking milestone. Process every payload to ensure new shipment information is incorporated into the shipment record.

Process every webhook payload as a shipment state update.

Do not assume every webhook payload represents a new tracking milestone. FedEx sends a new payload whenever new shipment information becomes available. For example, a delivered shipment may generate additional payloads when proof-of-delivery information, recipient information, or other shipment data are added or updated.

For each payload, ask:

• What tracking milestone changed?
• What shipment information has changed?
• Does the update affect a customer-facing application?
• Does the update trigger a notification?

Process shipment history

Monitor both scanEvent and previousEvents.

• scanEvent contains the current tracking milestone associated with the payload.
• previousEvents contains additional shipment history, including milestones that may not appear as the current scanEvent.

Some tracking milestones appear in previousEvents instead of being published as a new scanEvent. Applications that only process scanEvent can miss shipment updates and generate incomplete shipment histories. Process both collections to capture a complete view of the shipment.

Maintain a shipment record

Store each webhook payload and merge new information into the existing shipment record.

A complete shipment record provides near real-time visibility across:

• Shipment tracking dashboards
• Customer service applications
• Order management systems (OMS)

Update the shipment record with every payload to maintain the most accurate and complete view of the shipment.

Choose a notification strategy based on your business requirements and the level of shipment detail you want to provide.

FedEx tracking webhooks send updates for tracking milestones and shipment data changes in near real time. Use business rules to determine which updates are relevant to your business and which can be ignored.

Common notification strategies include:

Near real-time notifications

Send notifications immediately after a tracking milestone occurs.

Advantages

• Fastest customer communication
• Lowest latency

Consideration: Additional shipment information may not be available yet.

Rich notifications

Wait a few minutes after a tracking milestone so additional shipment information can arrive.

For example, after a delivered milestone, wait a few minutes to collect:

• Proof of Delivery (POD)
• Signature Proof of Delivery (SPOD)
• GPS Proof of Delivery
• Recipient information

Advantages

• More complete shipment updates for customers
• Fewer follow-up notifications
• Reduced customer support contacts

FedEx recommends waiting approximately five minutes after a delivered milestone because proof of delivery information is often added shortly after the initial delivery event.

Notification timing recommendations

Notification timing varies by customer and use case. However, the following recommendations are commonly used for post-purchase recipient notifications. For other notification types (business users, customer service representatives, and so on), choose a notification strategy that fits your use case.

• Estimated Delivery: Wait approximately 15 minutes after both the Commit Date and first estimated delivery date (EDD) are available.
• Out for Delivery: Send immediately or according to your business schedule (for example, daily at 8:00 AM).
• Delivered: Wait approximately 5 minutes to allow delivery enrichments to arrive.
• Delivery Attempt: Apply the same approach as Delivered to allow delivery information to arrive.

Building notification rules around business data

Not every shipment update requires notification. Define notification rules that support your business requirements.

Recommended approach

Do not trigger notifications based solely on eventCode.

Evaluate:

• Tracking milestone
• Required shipment data
• Business rules

Generate notifications only when required information is available.

This approach helps prevent:

• Duplicate notifications
• Missing delivery information
• Incomplete delivery notifications
• Unnecessary follow-up notifications

Use the appropriate timestamp based on your use case.

• eventCreateTime: When the shipment event occurred. Use it for customer-facing tracking history.
• Message sent time: When FedEx sent the webhook payload. Use it only for debugging and monitoring, not for customer-facing experiences.

eventCreateTime reflects when the shipment event occurred. FedEx does not update this value when additional shipment information is added later. For example, a delivered event keeps its original eventCreateTime even if subsequent payloads add proof-of-delivery information or other shipment updates. As a result, eventCreateTime should be used to identify when the event occurred, not when related shipment information was added.

In some cases, an event time may not be available. When this occurs, the timestamp can contain a default value of 00:00:00. Additional payloads may include a more accurate timestamp when it becomes available.

Best practices

• Process every webhook payload — every message may contain a new tracking event or shipment data update.
• Merge incremental updates into your existing shipment record.
• Monitor both scanEvent and previousEvents to capture the complete shipment history.
• Trigger customer notifications using business rules, not just raw events.
• Allow time for expected enrichments (example, PPOD, SPOD, GPS) before notifying customers.
• Design idempotent, resilient processing that manages duplicate and out-of-order messages.

Common integration issues

• Assuming every payload represents a new tracking milestone.
• Overwriting the shipment record with the latest payload.
• Relying only on scanEvent.
• Triggering notifications based solely on eventCode.
• Assuming the first delivered payload contains all delivery details.
• Assuming webhook messages arrive only once or in chronological order.

Process every webhook payload as a shipment state update. Store and merge shipment updates, monitor both scanEvent and previousEvents, and use business rules to determine when to update applications or notify customers.

This approach helps ensure accurate shipment visibility, complete tracking history, and more informed customer communications.