Tracking Sync
ShipLabel gets tracking updates two ways: it polls the carriers on a schedule, and it can also receive updates pushed to its webhook.
Scheduled Polling
A shiplabel_sync_tracking_statuses cron event runs twice daily. Each run checks up to 100 active labels with their carrier (spending at most about 20 seconds - anything left over is picked up on the next run) and saves new tracking events. When the latest event is a delivery, the order is marked Completed. The same run also removes label files older than the retention period.
Like all WP-Cron events, this only fires on a site visit by default. On low-traffic stores, set up a real system cron hitting wp-cron.php, or run it manually with WP-CLI: wp cron event run shiplabel_sync_tracking_statuses.
Tracking needs carrier access: USPS tracking works with your Client ID and Secret; FedEx tracking needs the Track API added to your FedEx project (see FedEx).
Tracking Webhook
For services that can push tracking updates instead of waiting for the next poll, ShipLabel accepts them at:
https://yourstore.com/shiplabel/tracking-webhook/Requests are JSON POSTs. ShipLabel reads:
| Data | Where |
|---|---|
| Carrier | X-Carrier header (usps or fedex), or a carrier field in the body. Defaults to usps |
| Tracking number | trackingNumber (USPS also TrackSummary.TrackingNumber) |
| Event description | USPS: eventDescription or TrackSummary.EventDescription. FedEx: eventDescription or scanEventDescription |
| Event time | eventTimestamp or date |
| Location | city or scanLocation.city |
Updates for tracking numbers ShipLabel doesn't know are acknowledged and ignored. For known labels, the event is saved and added to the order as a private note; a delivery event marks the order Completed.
Signing Requests
The Webhook secret on the Advanced tab is optional:
- Blank (default) - unsigned requests are accepted.
- Set - every request must include an
X-Webhook-Signature(orX-Hub-Signature-256) header ofsha256=followed by the HMAC-SHA256 of the raw request body, using the secret as the key. Requests with a missing or wrong signature are rejected with401.
Order Auto-Completion
Whether an update arrives via polling or the webhook, ShipLabel marks the order Completed as soon as the carrier reports delivery - no manual step required. Orders that are already completed are left unchanged.