Receive Starshipit Tracking Webhook
POST/api/webhooks/:integration_instance/starshipit
Called by Starshipit, not by an integrator. The tracking-notification URL to enter in the Starshipit dashboard for a connection. No bearer token.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Routing: the workspace is identified from the request host when it is the workspace's own domain, otherwise from integration_instance in the path; the Starshipit connection is then the one with that id (falling back to the workspace's first Starshipit connection). An empty body returns 400; if the workspace has no Starshipit connection the webhook is acknowledged and ignored.
Payload: Starshipit's tracking notification JSON. SKU.io reads order_number, tracking_number, tracking_status (e.g. Printed, Dispatched, Manifested, InTransit, OutForDelivery, Delivered, AttemptedDelivery, Exception, AwaitingCollection, Cancelled), carrier_name, carrier_service, shipment_date, last_updated_date and price_breakdown. The event is stored (see List Webhook Events) and processed in the background: it updates the cached Starshipit order and its fulfillment's tracking. Printed/Dispatched/Manifested are treated as shipped, Cancelled as cancelled, everything else as a tracking update.
Signature: Starshipit signs a webhook with the secret entered in its dashboard (Settings → Tracking & notifications) and sends the hex HMAC-SHA256 of the raw body in x-starshipit-signature. When the connection has a webhook secret saved in SKU.io, only webhooks with a matching signature are accepted; anything else returns 401. When no secret is saved, unsigned webhooks are accepted and stored with signature_valid: false.
Authentication: none (optional HMAC signature, see above).
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Bad Request
Response Headers
Unauthorized
Response Headers
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.