Qonversion Webhook MCP Server

qonversion-webhook

Qonversion POSTs JSON to the ingest URL. Two delivery families land in storage — often on the same connection:

1. Real-time subscription events — one JSON object per in-app purchase, trial, renewal, refund, or lifecycle change.
2. Scheduled raw-data reports — a daily JSON envelope pointing at a CSV export of subscription events for a rolling window (1, 3, or 7 days).

Each POST is one stored report. Inspect the latest payload to learn which family arrived before quoting metrics.

First moves

1. Latest report — default for “what happened last” or “did the morning export land”.
2. Classify the payload — event_name means a live subscription event; report_uid + link means a scheduled export envelope.
3. Recent reports — scan history for duplicate transaction_id, report_uid, or retry noise.
4. One report by id — after listing, when the user names a specific delivery.

Real-time event JSON (export.json)

Core identity and timing:

• event_name — lifecycle signal (trial_started, trial_converted, subscription_started, subscription_renewed, subscription_refunded, subscription_canceled, in_app_purchase, and related trial/subscription states). Revenue-bearing events often include revenue and price.
• user_id, custom_user_id, identity_id — Qonversion id, SDK-set custom id, and authenticated identity id.
• time — when the app store changed subscription status or Qonversion detected the change (Unix seconds).
• created_at — when Qonversion generated the webhook (may differ from time for cancel/billing-retry events).
• environment — "production" or "sandbox".
• platform — "iOS", "Android", or "Stripe".

Money and transaction:

• revenue — value, value_usd, currency, is_proceed (1 = net after store commission, 0 = gross), proceeds_rate (70 or 85). Refund events carry negative values when revenue is enabled upstream.
• price — gross price charged (value, value_usd, currency).
• transaction — transaction_id, original_transaction_id, expires, grace_period_expires, transaction_date, optional promo_offer_id. Renewals and product changes may carry a new transaction_id; billing-issue and cancel events may reuse the prior id.
• product_id, optional old_product_id / new_product_id for upgrades and downgrades.
• entitlements — array of active entitlement objects (id, active, expires, nested product, source, started); empty object when none.
• quantity, subscription_renew_count — consumable count and renewal counter when present.

Context and attribution:

• device_id, advertiser_id, app_id, app_version, sdk_version, project_name
• country (IP-based ISO alpha-2), optional storefront (App Store alpha-3, iOS only when configured)
• locale, subscription_group, user_install_date, properties (SDK user properties, e.g. _q_email)
• Optional asa_attribution — Apple Search Ads fields (campaign_id, adgroup_id, keyword_id, conversion_type, click_date, claim_type)

Scheduled report envelope (export.json)

Daily raw-data exports POST a compact JSON wrapper:

• report_uid — unique report id for this run.
• report_name — dashboard label for the schedule.
• project_key — Qonversion project identifier.
• platform — iOS or Android.
• link — URL to the CSV raw-data file (gzip-compressed exports are common upstream).
• send_at — scheduled send time as seconds from midnight UTC.
• period — coverage window length in seconds (often matches 1-, 3-, or 7-day included_range_days schedules).
• delete_at — when Qonversion removes the linked file from their servers.
• environment — integer: 1 production, 0 sandbox (differs from real-time events which use strings).

When the linked CSV is captured in storage, read export.rows for tabular preview — scheduled envelopes with metadata (report_uid, report_name, period, …) may land as a separate payload.json delivery alongside the fetched CSV file; list recent reports when the user asks about both envelope and rows.

Response shape

• export.json — parsed webhook body (event or scheduled envelope).
• export.rows / export.text — CSV preview or full body when a linked or attached export file was stored.
• source.captured_at — when the delivery landed here (not the same as time, created_at, or CSV event dates).

Operational order

1. Start with the latest report — do not guess a report id.
2. If captured_at is older than expected, say so — real-time events arrive asynchronously (often within tens of seconds); scheduled reports fire once daily at the configured UTC slot.
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 field notes.

Gotchas

• Read-only — cannot trigger a test send, replay an event, or change Qonversion subscription state from here.
• Two schemas — never assume every delivery is an event_name row; scheduled envelopes need the link (or captured CSV rows) for bulk analytics.
• environment type mismatch — string on live events, integer on scheduled report envelopes.
• time vs created_at vs CSV Event Date / Event Receive Date — use the field that matches the question (store change vs Qonversion detection vs export sorting).
• Revenue toggles upstream — some events omit revenue when disabled in integration settings; refund values may be negative.
• Retries — failed deliveries retry over ~24 hours; dedupe on transaction_id, report_uid, and captured_at when counting unique events.
• Link-only scheduled POSTs — when fetch fails or only the JSON envelope is stored, quote metadata from export.json; do not invent CSV figures without row data. Successful link fetch may produce two stored items (envelope JSON + CSV).