Update to Ship24 Tracking API

{
  "description": "Test and debug a Ship24 webhook receiver end to end. Use when asked to test your webhook, simulate tracking updates, replay webhook messages, run a local webhook receiver, or validate webhook handling. Provides a runnable HTTP server and walkthrough for creating sample shipments, triggering events, and auditing delivery.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 297
    },
    {
      "relative_path": "assets/icon-large.png",
      "size_in_bytes": 11655
    },
    {
      "relative_path": "assets/icon-small.png",
      "size_in_bytes": 3297
    },
    {
      "relative_path": "assets/webhook-pod.example.json",
      "size_in_bytes": 781
    },
    {
      "relative_path": "assets/webhook-tracking-events.example.json",
      "size_in_bytes": 2603
    },
    {
      "relative_path": "references/webhook-payloads.md",
      "size_in_bytes": 5617
    },
    {
      "relative_path": "scripts/receiver.mjs",
      "size_in_bytes": 4233
    }
  ],
  "name": "ship24-webhook-test",
  "skill_md_contents": "---\nname: ship24-webhook-test\ndescription: Test and debug a Ship24 webhook receiver end to end. Use when asked to test your webhook, simulate tracking updates, replay webhook messages, run a local webhook receiver, or validate webhook handling. Provides a runnable HTTP server and walkthrough for creating sample shipments, triggering events, and auditing delivery.\nlicense: MIT\n---\n\n# Testing Ship24 webhooks end to end\n\nVerify your receiver handles tracking updates correctly before going to production.\n\n## Quick start\n\n### 1. Start a local receiver\n\nFrom the installed skill directory (wherever your tool placed `ship24-webhook-test`), or from a clone of https://github.com/ship24/ship24-ai-plugin:\n\n```bash\ncd skills/ship24-webhook-test\nnode scripts/receiver.mjs\n```\n\nOutput:\n\n```\nShip24 webhook test receiver listening on http://localhost:3000 (POST any path)\nsecret check: off (set SHIP24_WEBHOOK_SECRET to enable); log: stdout\n```\n\nThe receiver:\n- Accepts `POST` on any path.\n- Responds `200 { ok: true }` immediately.\n- Logs to stdout (or a file if `LOG_FILE` is set).\n- Validates the `Authorization: Bearer <secret>` header if `SHIP24_WEBHOOK_SECRET` is set.\n- No external dependencies; uses Node 22 built-in `node:http`.\n\n**Env variables:**\n\n- `PORT`: Listen port (default 3000).\n- `SHIP24_WEBHOOK_SECRET`: Optional. When set, rejects requests whose `Authorization` header does not match using a constant-time comparison.\n- `LOG_FILE`: Optional. Append NDJSON logs to a file instead of stdout.\n\n### 2. Expose to the internet\n\nShip24 must reach your receiver. Use any tunnel you already have; examples:\n\n- **ngrok**: `ngrok http 3000`\n- **Cloudflare Tunnel**: `cloudflared tunnel --url http://localhost:3000`\n- **LocalTunnel**: `npx localtunnel --port 3000`\n\nNote the public HTTPS URL the tunnel prints.\n\n### 3. Configure the dashboard\n\n1. Log in to [dashboard.ship24.com](https://dashboard.ship24.com)\n2. Go to Integrations → Webhooks\n3. Paste the public URL into the Webhook URL field\n4. Copy the Webhook Secret and set it locally:\n\n```bash\nexport SHIP24_WEBHOOK_SECRET=your_webhook_secret\n```\n\n5. (Optional) Test using the dashboard button. This test does not originate from the documented outgoing IP `54.161.7.2`, so it is blocked if you restrict by IP.\n\n### 4. Create a sample tracker\n\nUse one of the bundled MCP tools, the Node SDK, or a direct HTTP call:\n\n**Via MCP (if available):**\n\n```\ncreate_tracker trackingNumber=SHIP24_SAMPLE_DELIVERED_000\n```\n\n**Via Node SDK:**\n\n```javascript\nimport { Ship24 } from 'ship24';\n\nconst client = new Ship24({ apiKey: process.env.SHIP24_API_KEY });\nconst tracker = await client.trackers.create({\n  trackingNumber: 'SHIP24_SAMPLE_DELIVERED_000'\n});\nconsole.log('Tracker:', tracker.trackerId);\n```\n\n**Via curl:**\n\n```bash\ncurl -X POST https://api.ship24.com/public/v1/trackers \\\n  -H \"Authorization: Bearer $SHIP24_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"trackingNumber\": \"SHIP24_SAMPLE_DELIVERED_000\"}'\n```\n\nSample tracking numbers:\n\n- `SHIP24_SAMPLE_DELIVERED_000` - Delivered\n- `SHIP24_SAMPLE_IN_TRANSIT_000` - In transit\n- `SHIP24_SAMPLE_EXCEPTION_000` - Exception\n- Change the last three digits to mint a fresh tracker with the same event sequence (e.g., `SHIP24_SAMPLE_DELIVERED_123`).\n\n### 5. Watch deliveries\n\nAs you create the tracker, Ship24 discovers events and sends webhooks. Check your receiver logs:\n\n```\n{\"timestamp\":\"2025-03-04T17:13:02.114Z\",\"method\":\"POST\",\"path\":\"/\",\"authorization\":\"Bearer [masked]\",\"topic\":\"tracking/events\",\"messageId\":\"...\",\"trackerId\":\"...\",\"trackingNumber\":\"SHIP24_SAMPLE_DELIVERED_000\",\"statusMilestone\":\"delivered\",\"eventId\":\"...\",\"statusCode\":\"delivery_delivered\",\"occurrenceDatetime\":\"2025-03-04T17:12:57\"}\n```\n\n### 6. Replay with resend\n\nTo replay all webhooks for a tracker (useful if you dropped messages):\n\n**Via MCP:**\n\n```\nresend_webhooks trackerId=<trackerId>\n```\n\n**Via curl:**\n\n```bash\ncurl -X POST https://api.ship24.com/public/v1/trackers/<trackerId>/webhook-events/resend \\\n  -H \"Authorization: Bearer $SHIP24_API_KEY\"\n```\n\nThe receiver logs again. It is your responsibility to deduplicate on `metadata.messageId` and `events[].eventId`.\n\n### 7. Audit with webhook history\n\nDownload the full delivery history for a tracker:\n\n**Via MCP:**\n\n```\ndownload_webhook_history trackerId=<trackerId>\n```\n\n**Via curl:**\n\n```bash\ncurl -X GET \"https://api.ship24.com/public/v1/trackers/<trackerId>/webhook-history/download\" \\\n  -H \"Authorization: Bearer $SHIP24_API_KEY\" \\\n  -o webhook-history.json\n```\n\nReturns metadata and a log of every sent webhook delivery (pending ones are excluded): request body, response status, response headers, and timestamps.\n\n### 8. Test offline with curl\n\nTo test your receiver without creating a real tracker:\n\n```bash\ncurl -X POST http://localhost:3000 \\\n  -H \"Authorization: Bearer your_webhook_secret\" \\\n  -H \"Content-Type: application/json\" \\\n  -d @assets/webhook-tracking-events.example.json\n```\n\nThe example file is a sample tracking webhook payload. Your receiver should log the event.\n\n## Receiver behavior\n\nThe bundled `scripts/receiver.mjs`:\n\n- **Accepts `POST` on any path**: `/`, `/webhooks`, `/tracking`, etc. all work.\n- **Responds immediately**: reads the body, answers 200 with `{ ok: true }`, then logs.\n- **Validates secret**: If `SHIP24_WEBHOOK_SECRET` is set, rejects requests without a matching `Authorization: Bearer <secret>` header (401). Comparison is constant-time to mitigate timing attacks.\n- **Rejects malformed JSON**: non-JSON bodies receive 400 and are still logged; bodies over 1 MB receive 413 and the connection is closed.\n- **Logs to stdout or file**: Each webhook logged as a single-line JSON object (NDJSON).\n- **Logs fields of interest**: timestamp, method, path, authorization scheme (the secret is masked), topic, messageId, trackerId, clientTrackerId, trackingNumber, statusMilestone, each event's eventId, statusCode and occurrenceDatetime; for proof-of-delivery messages, the PoD status and content type.\n- **No external dependencies**: Uses only Node 22 built-in modules.\n\n## Testing checklist\n\nBefore going to production:\n\n- [ ] Receiver logs incoming webhooks without errors.\n- [ ] Secret validation works: requests without the correct header are rejected.\n- [ ] Response is sent before async processing.\n- [ ] Sample tracker triggers webhook delivery once Ship24 has fetched its events (not instant).\n- [ ] Resend endpoint replays old messages (receiver must dedupe).\n- [ ] Webhook history download works and shows delivery attempts and responses.\n- [ ] Multiple shipments (with different statuses) all arrive correctly.\n- [ ] Receiver handles the IP allowlist (`54.161.7.2`) if you restrict by IP at production.\n- [ ] Offline curl test with example JSON parses without errors.\n\n## Next steps\n\nAfter confirming delivery:\n\n1. Deploy your receiver to production (public HTTPS URL).\n2. Update the dashboard webhook URL.\n3. Implement deduplication on `metadata.messageId` and `events[].eventId`.\n4. Implement ordering: compare `occurrenceDatetime` to the latest stored event.\n5. Add async processing: return 200, then apply business logic (update shipment, send notifications, etc.).\n6. Set up logging and monitoring for webhook failures.\n7. Keep the resend endpoint and the webhook history download in your debugging toolbox.\n\nSee the `ship24-webhooks` skill for full implementation details, payload structure, and best practices.\n\n## Key links\n\n| Resource | URL |\n| --- | --- |\n| Webhook documentation | https://docs.ship24.com/webhooks/overview |\n| Resend endpoint | https://docs.ship24.com/tracking-api-reference/#/operations/resend-webhooks |\n| Webhook history | https://docs.ship24.com/tracking-api-reference/#/operations/download-webhook-history |\n| Sample tracking numbers | Ship24 Tracking Statuses skill |\n"
}