Webhook Ingest

Webhook Ingest

Reports land in storage when upstream schedulers POST files; tools read what is already stored. There is no pull API — you cannot fetch live data from the source. If nothing has arrived yet, expect errors or empty lists; never invent report figures.

First moves

1. Latest report — default for metrics, pacing, forecasts, occupancy, revenue, or “what did the report say”.
2. Report freshness — when timing matters, use source.captured_at and source.filename from the latest response before listing history.
3. Recent reports — list when comparing runs, checking duplicates, or resolving which file the user means.
4. One report by id — after listing, fetch a specific stored report when the user points at a date or id.

Response shape

• source — captured_at, filename, format, purpose (connection label), stale.
• export — stored file content:
  • rows — parsed CSV rows (dict per row); often capped (~5) with rows_truncated: true.
  • text — full raw body when rows truncate or the file is not tabular.
  • json — parsed JSON when the file was JSON.

Use rows for column-level questions. When rows_truncated is true, use text or ask the user to narrow scope.

Operational order

1. Start with the latest report — do not guess a report id.
2. If captured_at is older than the user expects, say so; upstream sends on their schedule (often hourly at most).
3. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
4. Read ## This connection in the skill supplement for column semantics — each upstream report differs.

Gotchas

• Read-only — cannot trigger a new delivery or change ingest settings.
• Empty — no stored reports means nothing has landed yet; say no report is available.
• Zip-wrapped CSV — stored as unpacked CSV in export.text / export.rows.
• Link-style POST bodies — upstream may send a JSON wrapper with a file URL; storage holds the fetched file content.
• Each delivery is one report — latest is the newest capture, not a merged history.
• Connection status — only when the user asks about setup, ingest URL, or whether anything has arrived (not for report content questions).