# Use webhooks and tracking updates
URL: https://support.starshipit.com/articles/14700000001008-use-webhooks-and-tracking-updates
Canonical: https://support.starshipit.com/articles/14700000001008-use-webhooks-and-tracking-updates
Markdown: https://support.starshipit.com/articles/14700000001008-use-webhooks-and-tracking-updates.md
Updated: 2026-06-18

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Use Starshipit webhooks and tracking lookups to keep another system updated after labels are created.

Use webhooks or tracking lookups when another system needs to know that an order has shipped, manifested, or received updated delivery tracking information. This is the canonical Developer Center guide for tracking writeback, webhook setup, receiver behaviour, and polling fallbacks.

## Choose webhook or polling

| Approach | Use when | Trade-off |
| --- | --- | --- |
| Webhooks | Your system can receive inbound HTTP requests | Faster updates, but you need reliable receiving, retries, and deduplication. |
| Polling | Your system cannot receive webhooks or needs scheduled reconciliation | Simpler infrastructure, but updates are less immediate and request volume is higher. |
| Hybrid | You want real-time updates plus a safety net | Webhooks handle normal updates and polling catches missed events. |

## Recommended webhook workflow

1. In Starshipit, go to **Settings > Customer Notifications** or **Settings > Tracking & notifications**.
2. Add your HTTPS notification endpoint URL.
3. Optional: add or generate a webhook secret key.
4. Print or update a test shipment so Starshipit can send a webhook event.
5. Receive the webhook payload in your system.
6. Validate the payload shape and required identifiers.
7. Validate the `X-Starshipit-Signature` header if you configured a secret.
8. Match the event to your source order.
9. Update the source system with tracking or shipment status.
10. Store the event ID, order number, tracking number, and received timestamp.
11. Ignore duplicate events that have already been processed.

## Supported webhook data

Starshipit webhooks are tracking and shipment notification events. Payloads include order, carrier, tracking, and status fields.

| Field | Type | Description |
| --- | --- | --- |
| `order_number` | string | The order number from the source ecommerce platform or integration. |
| `carrier_name` | string | The courier used for the shipment. |
| `carrier_service` | string | The courier service used for the shipment. |
| `shipment_date` | datetime | The local date when the label was generated. |
| `tracking_number` | string | The courier tracking number. |
| `tracking_status` | string | The latest tracking status from Starshipit or the courier. |
| `last_updated_date` | datetime | The latest tracking update timestamp. |

Supported tracking statuses include `Printed`, `Dispatched`, `InTransit`, `OutForDelivery`, `Delivered`, `PickupInStore`, `AttemptedDelivery`, `Exception`, `AwaitingCollection`, `Cancelled`, `Manifested`, `ReturnPickupPrinted`, `ReturnDropoffPrinted`, `DroppedOff`, `ReturnLink`, and `ReturnLabel`.

## Recommended polling workflow

1. Store the Starshipit order ID or order number when you create or import the order.
2. Query the relevant order or tracking endpoint on a schedule.
3. Update only records that changed since your last successful sync.
4. Back off when you receive rate-limit responses.
5. Run a periodic reconciliation job for recently shipped orders.

## Endpoint map

[Open the Starshipit API reference](/developers/api-reference/starshipit#tracking) for tracking request fields and response models.

| Step | Endpoint | Use it to |
| --- | --- | --- |
| Receive webhooks | `POST /callback/` | Accept tracking updates from Starshipit at your configured endpoint. |
| Poll tracking | [GET /api/track](/developers/api-reference/starshipit#endpoint-tracking-get-api-track-tracking) | Reconcile tracking status when webhooks are unavailable or missed. |
| List printed shipments | [GET /api/orders/shipments?status=recently_printed](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-shipments-status-recently-printed-list-orders-printed-or-unmanifested) | Find recently printed or unmanifested shipments. |
| List shipped orders | [GET /api/orders/shipped](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-shipped-list-orders-shipped) | Reconcile source-system shipment status. |

## Expected receiver behaviour

1. Receive the webhook payload.
2. Validate the payload shape and required identifiers.
3. Validate the `X-Starshipit-Signature` header if you configured a secret.
4. Store the raw event or a normalised event record.
5. Return `200` as soon as the event is accepted for processing.
6. Process long-running source-system updates outside the request path.
7. Ignore duplicate events that have already been processed.

## Example payload

```json
{
  "order_number": "API-TEST-1001",
  "carrier_name": "Australia Post",
  "carrier_service": "7B05",
  "shipment_date": "2026-06-18T09:30:00Z",
  "tracking_number": "TESTTRACK123",
  "tracking_status": "Dispatched",
  "last_updated_date": "2026-06-18T09:35:00Z"
}
```

## Design for retries and duplicates

Webhook receivers should be idempotent. Receiving the same event twice should not create duplicate fulfilment updates, duplicate emails, or duplicate source-system notes.

For both webhooks and polling, log:

- Event or request timestamp.
- Source order number.
- Starshipit order ID, if available.
- Tracking number.
- Carrier and service.
- Processing result.

Good idempotency keys include:

- A stored event ID if your receiver creates one.
- `order_number`, `tracking_number`, `tracking_status`, and `last_updated_date`.
- The source order ID plus the final tracking status your system stores.

## Failure handling

| Failure | Recommended handling |
| --- | --- |
| Receiver cannot parse JSON | Return a non-success response and log the raw body safely. |
| Source order cannot be found | Store the event for manual matching or scheduled reconciliation. |
| Source system is unavailable | Queue the event and retry from your own job processor. |
| Duplicate event | Return success and do not repeat downstream side effects. |

## Verify tracking updates

Create a test order, generate a label, and confirm the source system receives the tracking number and status you expect. Then resend or replay the same event to confirm duplicate handling works.

## Related guides

- [Webhook notifications](/articles/360000376436-webhook-notifications)
- [Starshipit API fundamentals](/articles/developer-center/starshipit-api/api-fundamentals)
- [Testing guidance](/articles/developer-center/getting-started/testing-guidance)
- [Starshipit API reference](/developers/api-reference/starshipit#tracking)