SamCart Webhook MCP Server

samcart-webhook

SamCart notify-URL webhooks POST JSON when checkout, order, subscription, refund, or course events fire. Each POST is one stored report. Shape depends on which trigger fired upstream — inspect export.json on the latest delivery rather than assuming one fixed schema.

Payload shape

Most purchase and subscription events share nested objects:

• type — event discriminator. Common values include Order, Refund, PartialRefund, UpsellPurchased, RecurringPaymentSucceeded, RecurringPaymentFailed, Cancel, SubscriptionDelinquent, SubscriptionRestarted, and SubscriptionChargeRefunded.
• product — single line item when the trigger fires per product (id, name, price, optional quantity, shipping, tax, transaction_id, sku, subscription_id, funnel_info on upsells).
• products — array of line items on Order Completed only (each entry may include status, transaction_id, subscription_id, funnel_info).
• customer — buyer identity and billing (first_name, last_name, email, phone_number, customer_id; billing may use billing_address/billing_city/… or billing_address_line1/billing_address_line2/…).
• order — order metadata (id, total, created_at, ip_address, stripe_id, subscription_id, processor, total_tax, total_shipping, transaction_id as string or array, shipping address fields, custom_fields, upsell_custom_fields, utm_parameters, custom_url_parameters).
• affiliate — object or empty array depending on event.
• Refund events — may add processor and refund_transaction_id; order.total reflects remaining balance after partial refunds.
• Subscription charge success — may include charge_id and fuller billing/shipping address fields on customer and order.

Prospect Created and some lightweight events use a flatter top-level shape (product_id, product_name, product_price, currency, address arrays) without the usual type/product/order nesting.

Missing upstream values arrive as JSON null.

First moves

1. Latest report — default for “what order or subscription event happened last”; read export.json.type and nested customer / order / product or products.
2. Recent reports — list when comparing multiple purchases, refunds, subscription charges, or suspected duplicate posts for the same order.id.
3. One report by id — after listing, when the user names a specific stored delivery.

Response shape

• export.json — parsed notify-URL body.
• export.text — raw body when JSON is large or non-object.
• source.captured_at — when the POST landed here (use order.created_at inside JSON for upstream order time when present).

Operational order

1. Start with the latest report — do not guess a report id.
2. If captured_at is older than expected, say so — SamCart sends when the configured trigger fires, not on demand.
3. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
4. Read ## This connection in the skill supplement for product- or funnel-specific field notes.

Gotchas

• Read-only — cannot replay charges, issue refunds, or change SamCart orders from here.
• Per-product vs whole order — Product Purchased fires once per line item; Order Completed sends one POST with a products array. Do not treat missing products as “no items” on per-product events.
• Schema varies by trigger — refunds, cancellations, and failed recurring charges carry slimmer customer/order blocks than full purchase payloads.
• Duplicate posts — the same order.id may appear across multiple stored reports when several triggers fire; dedupe using type, product.id, and source.captured_at.
• Address field names — billing and shipping keys differ between older and newer samples; read what is present instead of expecting one naming scheme.
• Custom checkout data — order.custom_fields may be an array or a single object with name, slug, and value depending on event age and trigger.