Skip to main content

17TRACK Webhook (TRACKING_UPDATED)

POST 
/webhooks/seventeentrack/:webhook_token

This endpoint is INCOMING — it is called by 17TRACK, not by SKU.io clients. Documented here for reference only.

Full URL shape: POST /webhooks/seventeentrack/{webhook_token}. The token in the URL identifies the tenant + instance; the sign request header is sha256(event + '/' + <data JSON exactly as sent> + '/' + api_key) computed with the instance's 17TRACK API key — verified by VerifySeventeenTrackWebhook middleware before the controller runs.

Envelope (v2.4):

{
  "event": "TRACKING_UPDATED" | "TRACKING_STOPPED",
  "data": { ... carrier-event payload ... }
}

Behavior:

  • Empty body → 200 { status: 'acknowledged' } (avoids 17TRACK retry storm).
  • Missing event key → 200 { status: 'ignored' }.
  • Valid payload → 200 { status: 'success' } and a background job is dispatched for async ingest. Out-of-order events (older last_event_at than what's already stored) are dropped inside the repository.

Why 200 for non-actionable payloads? 17TRACK retries non-2xx responses for several hours, so empty or event-less payloads are acknowledged with 200 to avoid retry storms.

Rejections (17TRACK will retry these):

  • 404 — the token is missing or unknown (plain-text body), or no 17TRACK instance is connected for it ({"message": "No instance"})
  • 401 — the sign header is missing (Missing signature), does not match (Invalid signature), or the instance has no API key (Misconfigured)
  • 503 — webhook routing is temporarily unavailable

Request​

Responses​

OK

Response Headers
    Content-Type