FastSpring Webhook MCP Server

FastSpring Webhook

Each stored delivery is one FastSpring server webhook POST — a JSON object with an events array. A single POST may batch several events; each item has its own type, id, live, created (epoch ms), and a data object whose shape depends on the event type. Tools read what already landed; there is no pull API and no way to replay or mutate store state from here.

First moves

1. Latest report — default for “what order or subscription event happened last”.
2. Inspect export.json.events[] — read each event’s type before quoting order or subscription fields.
3. Recent reports — scan history when comparing rebills, deduping retries, or tracing a customer across deliveries.
4. One report by id — after listing, when the user points at a specific capture.

Payload envelope

• events[] — batched events in one POST; iterate every element, not just the first.
• events[].type — dotted name such as order.completed, subscription.activated, subscription.charge.completed, subscription.canceled, return.created.
• events[].id — stable delivery id for automatic retries (same id resends until acknowledged); manual retries get new ids.
• events[].live — true for live orders, false for test-mode purchases.
• events[].created — when FastSpring created the event (epoch ms); may differ from source.captured_at.
• events[].data — event-specific payload (order object, subscription object, account object, etc.).

Order events (events[].data when type starts with order.)

Common order types: order.completed (payment succeeded and fulfillments finished), order.failed, order.canceled, order.payment.pending, order.approval.pending, chargeback.created.

Useful order fields when present in data:

• Identity — id / order, reference, buyerReference.
• Money — total, subtotal, tax, discount plus *Display and *InPayoutCurrency variants; currency, payoutCurrency.
• Customer — nested account.contact (name, email, company, phone) or top-level customer; account.address for billing/shipping.
• Timing — changed, changedInSeconds, changedDisplayISO8601.
• Line items — items[] with product path, quantity, and price fields.
• Subscriptions on the order — subscriptions object keyed by subscription id when the purchase included recurring products.

order.completed fires only after payment succeeds and fulfillments complete — not for failed payments or failed fulfillments. For subscription products it fires on the initial purchase only; recurring rebills do not emit order.completed (they emit subscription.charge.completed instead).

Subscription events (events[].data when type starts with subscription.)

Common subscription types: subscription.activated (new subscription or trial start), subscription.charge.completed (successful rebill or proration), subscription.charge.failed, subscription.updated, subscription.canceled, subscription.uncanceled, subscription.deactivated, subscription.payment.overdue, subscription.payment.reminder, subscription.trial.reminder, subscription.paused, subscription.resumed.

Useful subscription fields when present in data:

• Identity — id / subscription, linked quote.
• State — state (active, trial, overdue, canceled, deactivated), active boolean.
• Product — product path id, display name, quantity.
• Money — price, subtotal, discount with display and payout-currency variants.
• Account — nested account with contact.email and account.id.
• Timing — changed, changedInSeconds, next period / period end fields when included.

subscription.activated covers new subscriptions including trials; it does not fire on rebills. Use subscription.charge.completed for recurring charge success.

Webhook expansion

When the upstream store has webhook expansion enabled, data embeds full account, product, and order/subscription objects. Without expansion, data may contain only resource ids — do not assume nested contact or line-item fields exist; read what the latest JSON actually contains.

Response shape

• export.json — parsed webhook body; start with events[].
• export.text — raw body when JSON is large or parsing failed.
• source.captured_at — when the POST landed here, not necessarily the FastSpring event time — compare with events[].created.

Operational order

1. Start with the latest report — do not guess a report id.
2. Parse events[] and state each event’s type before summarizing.
3. If captured_at is older than expected, say so — rebills and batch jobs may queue webhooks.
4. List recent reports only for history, duplicate suspicion, or tracing an order/subscription across time.
5. Read ## This connection in the skill supplement for store-specific product paths or field notes.

Gotchas

• Read-only — cannot place orders, cancel subscriptions, or acknowledge deliveries upstream.
• Batched POSTs — one stored delivery may hold multiple unrelated events; do not treat the whole body as a single order.
• Duplicate retries — automatic retries reuse the same events[].id; dedupe on id when counting unique events across captures.
• Test vs live — check events[].live and order live before quoting production revenue.
• Rebill vs initial order — subscription renewals appear as subscription.charge.*, not order.completed.
• Schema varies by event type and expansion — inspect the latest JSON rather than assuming every field is present.
• Empty — no stored reports means nothing has arrived yet; say no webhook is available.