FLYR Insights Webhook

flyr-webhook

FLYR Insights scheduled deliveries land as stored reports when the upstream scheduler fires. Each POST is one capture — multipart file uploads, a JSON link wrapper, or zip-wrapped CSV depending on how the schedule was configured. There is no pull API; read what already landed. If nothing has arrived yet, expect errors or empty lists — never invent KPI figures.

First moves

1. Latest report — default for pacing, forecasts, occupancy, revenue, ADR, or “what did the scheduled export say”.
2. Report freshness — when timing matters, check source.captured_at and source.filename before quoting numbers.
3. Recent reports — list when comparing runs, spotting duplicate filenames, or resolving which delivery the user means.
4. One report by id — after listing, fetch a specific stored report when the user points at a date or id.
5. Connection status — only when the user asks whether anything has arrived yet (not for report content questions).

What upstream deliveries look like

FLYR Insights webhooks typically arrive in one of these shapes (all normalize to stored file content):

• Link JSON — a POST body like { "url": "..." } when the export is too large to attach inline; storage holds the fetched file bytes from that link.
• Multipart FormData — file attachments where each part’s field name is the filename and the value is file content (CSV, PDF, PNG, or XLSX depending on schedule format).
• Zip-wrapped CSV — dashboard CSV schedules deliver multiple .csv files inside a zip; storage unpacks the CSV automatically for tabular preview.

Dashboard-level schedules may include several tiles — expect multiple CSVs or a zip bundle, not a single fixed table. Tile-level schedules usually map to one export file.

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 stored payload was JSON.

Use rows for column-level questions. When rows_truncated is true, use text or ask the user to narrow scope. PDF and PNG attachments may have limited tabular preview — prefer text or describe that the delivery is visual.

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 daily or weekly; custom cadences can run as often as hourly).
3. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
4. Read ## This connection in the skill supplement for property-specific column or KPI notes — each scheduled dashboard differs.

Gotchas

• Read-only — cannot trigger “Test Now”, reschedule, or change upstream delivery settings from here.
• Variable columns — do not assume fixed KPI names (occupancy, ADR, RevPAR, etc.); read headers from the latest export.rows or connection notes.
• Each delivery is one report — latest is the newest capture, not a merged history across schedules.
• Multiple files per POST — a dashboard zip may represent several tiles; filename and preview reflect what was unpacked first.
• Link exports — the stored file is the fetched content, not the wrapper JSON; if fetch failed at ingest time, the report may be empty or error-shaped.
• Filters and timezone — upstream schedules can apply dashboard filters and query timezones; two deliveries with the same schedule name may differ if filters changed upstream.