Draft improvements from assistant conversations: webhook payload + stop tracking clarifications

[mintlify]

Summary

Close recurring documentation gaps surfaced by recent assistant conversations around webhook payload semantics and where tracking is stopped in the API.

Changes

• Webhook Payloads: added a "One notification per container" section (container-scoped events fire per container, not per vessel move) and idempotency guidance.
• Webhook Payloads: called out the events that ship with a minimal included array (container.transport.available, not_available, the three estimated.* events, and container.pickup_appointment.changed) and how to resolve container/BOL details via a follow-up API call.
• Webhook Payloads: added a compact table for extracting timestamp, container number, BOL, voyage number, and location from included records.
• Tracking Request Lifecycle: added a "Stopping tracking programmatically" subsection explaining that stop/resume is a shipment-level operation, has no tracking-request or per-container equivalent, and applies to every container on the shipment regardless of how tracking was initiated.

Context

Multiple recent assistant conversations repeatedly asked (a) whether one webhook covers multiple containers on the same vessel, (b) where to find the container number and BOL in available / not_available / estimated.* / pickup_appointment.changed payloads, and (c) how to stop tracking at the tracking-request level. The docs implied these answers but did not state them directly.

Greptile Summary

This PR adds documentation clarifications in two areas surfaced by recurring assistant conversations: webhook payload semantics and programmatic tracking control. The changes are documentation-only with no code impact.

• Webhook Payloads (payloads.mdx): Adds a "One notification per container" section with idempotency guidance, a list of events that ship with a minimal included array (notably container.transport.available, not_available, and the three estimated.* events), and a quick-reference table for extracting timestamp, container number, BOL, voyage number, and location from included records.
• Tracking Request Lifecycle (tracking-request-lifecycle.mdx): Adds a "Stopping tracking programmatically" subsection clarifying that stop/resume is a shipment-level operation with no per-container or per-tracking-request equivalent, and that stopping a shipment halts tracking for all its containers regardless of how tracking was initiated.

Confidence Score: 4/5

Documentation-only change; no runtime impact. The new content is directionally accurate but two clarity issues should be addressed before publishing.

The tracking-request-lifecycle subsection lists tracking request status values as pending, created, failed, tracking_stopped — omitting awaiting_manifest, which is an actual reachable status documented just above. Integrators reading this list as exhaustive would miss a state their code needs to handle.

Both changed files need a second look: tracking-request-lifecycle.mdx for the incomplete status list, and payloads.mdx for the unresolved tension between the reference-object-types table and the new minimal-included section.

Important Files Changed

Filename	Overview
docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx	Adds a "Stopping tracking programmatically" subsection; the parenthetical list of status values omits the awaiting_manifest state documented earlier in the same file, making the list appear exhaustive when it isn't.
docs/api-docs/webhooks/payloads.mdx	Adds "One notification per container" section, minimal-included-array event list, and a common-fields extraction table; the existing reference object types table implicitly promises container/shipment inclusion for all container.transport.* events, which now conflicts with the new minimal-included exceptions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Container-scoped event fires] --> B{Event type}
    B -->|container.transport.available\ncontainer.transport.not_available\ncontainer.transport.estimated.*\ncontainer.pickup_appointment.changed| C[Minimal included array\nNo shipment/container embedded]
    B -->|All other container.transport.*\ncontainer.updated, container.created\ntracking_request.*, etc.| D[Full included array\nShipment + container + transport_event]
    C --> E[Follow reference_object relationship\nGET /containers/:id or GET /shipments/:id]
    D --> F[Extract fields from included\ntimestamp, number, BOL, voyage, locode]
    E --> G[Route to correct record\nusing container id or number]
    F --> G
    G --> H[Use data.id as idempotency key\nfor deduplication]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Container-scoped event fires] --> B{Event type}
    B -->|container.transport.available\ncontainer.transport.not_available\ncontainer.transport.estimated.*\ncontainer.pickup_appointment.changed| C[Minimal included array\nNo shipment/container embedded]
    B -->|All other container.transport.*\ncontainer.updated, container.created\ntracking_request.*, etc.| D[Full included array\nShipment + container + transport_event]
    C --> E[Follow reference_object relationship\nGET /containers/:id or GET /shipments/:id]
    D --> F[Extract fields from included\ntimestamp, number, BOL, voyage, locode]
    E --> G[Route to correct record\nusing container id or number]
    F --> G
    G --> H[Use data.id as idempotency key\nfor deduplication]

Loading

Comments Outside Diff (1)

1. docs/api-docs/webhooks/payloads.mdx, line 70-73 (link)

   Reference object types table now contradicts the new minimal-included section

   The "Reference object types" table states that container.transport.* events "Includes the transport event, container, shipment, and location records that are available." The new "Events with a minimal included array" subsection lists container.transport.available and container.transport.not_available as events where container/shipment records are not embedded. The trailing "that are available" qualifier softens the contradiction, but a reader who sees the table first will expect those records to be present and may not reach the caveat. Consider adding a forward-reference note to the table row (e.g., "see exceptions below") or explicitly carving out those two events in the table.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/api-docs/webhooks/payloads.mdx
   Line: 70-73
   
   Comment:
   **Reference object types table now contradicts the new minimal-included section**
   
   The "Reference object types" table states that `container.transport.*` events "Includes the transport event, container, shipment, and location records that are available." The new "Events with a minimal `included` array" subsection lists `container.transport.available` and `container.transport.not_available` as events where container/shipment records are **not** embedded. The trailing "that are available" qualifier softens the contradiction, but a reader who sees the table first will expect those records to be present and may not reach the caveat. Consider adding a forward-reference note to the table row (e.g., "see exceptions below") or explicitly carving out those two events in the table.
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx:81
**Incomplete status list omits `awaiting_manifest`**

The parenthetical list of tracking request `status` values — `pending`, `created`, `failed`, `tracking_stopped` — is missing `awaiting_manifest`, which is documented earlier in this same file as a real `status` value ("The `status` changes to `awaiting_manifest` and Terminal49 keeps checking your request daily"). Developers reading the new subsection may treat the list as exhaustive and be surprised when their request transitions to a state they haven't handled.

### Issue 2 of 2
docs/api-docs/webhooks/payloads.mdx:70-73
**Reference object types table now contradicts the new minimal-included section**

The "Reference object types" table states that `container.transport.*` events "Includes the transport event, container, shipment, and location records that are available." The new "Events with a minimal `included` array" subsection lists `container.transport.available` and `container.transport.not_available` as events where container/shipment records are **not** embedded. The trailing "that are available" qualifier softens the contradiction, but a reader who sees the table first will expect those records to be present and may not reach the caveat. Consider adding a forward-reference note to the table row (e.g., "see exceptions below") or explicitly carving out those two events in the table.

_{Reviews (1): Last reviewed commit: "docs: clarify per-container webhooks, mi..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Building	Preview, Comment	Jul 6, 2026 4:10pm

[greptile-apps]

Incomplete status list omits awaiting_manifest

The parenthetical list of tracking request status values — pending, created, failed, tracking_stopped — is missing awaiting_manifest, which is documented earlier in this same file as a real status value ("The status changes to awaiting_manifest and Terminal49 keeps checking your request daily"). Developers reading the new subsection may treat the list as exhaustive and be surprised when their request transitions to a state they haven't handled.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx
Line: 81

Comment:
**Incomplete status list omits `awaiting_manifest`**

The parenthetical list of tracking request `status` values — `pending`, `created`, `failed`, `tracking_stopped` — is missing `awaiting_manifest`, which is documented earlier in this same file as a real `status` value ("The `status` changes to `awaiting_manifest` and Terminal49 keeps checking your request daily"). Developers reading the new subsection may treat the list as exhaustive and be surprised when their request transitions to a state they haven't handled.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!