Hotmart Webhook MCP Server

Hotmart Webhook

Each stored delivery is one JSON POST from Hotmart when a product event fires — purchase lifecycle, subscription change, cart abandonment, or Club activity. Read what already landed; you cannot trigger refunds, replays, or subscription changes from here.

First moves

1. Latest report — default for “what happened last” or “who bought what”.
2. Read export.json.event — purchase vs subscription vs cart vs Club before interpreting fields.
3. Recent reports — list when comparing renewals, refunds, duplicate transactions, or funnel volume.
4. One report by id — after listing, when the user names a transaction or event id.

Payload envelope (version 2.0.0)

Top-level fields repeat on every event:

• id — unique Hotmart event id (dedupe key alongside data.purchase.transaction).
• creation_date — when Hotmart created the event, in milliseconds since epoch (not the same as source.captured_at).
• event — event type string (see below).
• version — schema version; expect 2.0.0.
• data — sale details; which nested objects appear depends on the event.

Purchase event types

Common event values on one-time and subscription sales:

Also watch for PURCHASE_OUT_OF_SHOPPING_CART (cart abandonment) — lead data, not a completed sale.

Subscription event types

Subscription-specific event values (often include data.subscription):

On recurring products, purchase events may still carry data.subscription with plan and subscriber context.

Club event types

Members-area activity (may omit full purchase objects):

• CLUB_FIRST_ACCESS — first access to Hotmart Club content.
• CLUB_MODULE_COMPLETED — module marked complete.

Key data fields to read

Product — data.product.id, data.product.ucode, data.product.name; bundle sales add data.product.content.products[].

Buyer — data.buyer.email, data.buyer.name, data.buyer.document, data.buyer.checkout_phone; address fields appear only when collected at checkout.

Purchase — data.purchase.transaction (stable id, e.g. HP…), data.purchase.status, data.purchase.price, data.purchase.full_price, data.purchase.approved_date, data.purchase.payment.type (e.g. PIX, CREDIT_CARD, BILLET), data.purchase.recurrence_number (which subscription cycle), data.purchase.date_next_charge, data.purchase.offer.code / offer.name.

Subscription — data.subscription.status (ACTIVE, OVERDUE, CANCELLED_BY_CUSTOMER, CANCELLED_BY_SELLER, etc.), data.subscription.subscriber.code (unique per product subscription), data.subscription.plan.id / plan.name.

Affiliate — data.affiliates[] with affiliate_code and name when an affiliate drove the sale.

Commissions — data.commissions[] with value, currency_value, source (PRODUCER, AFFILIATE, COPRODUCER, ADDON, MARKETPLACE).

Order bump — data.purchase.order_bump.is_order_bump and parent_purchase_transaction link add-on checkouts to the main transaction.

Physical / shipping — data.product.is_physical_product, data.shipping.cost, carrier, and fulfillment when present.

High-ticket plans — data.purchase.flexPayPlan with enrollmentStatus and planCharges[] for staged payment schedules.

Response shape (stored delivery)

• export.json — parsed Hotmart event object; start here.
• export.text — raw body if JSON is large or malformed.
• source.captured_at — when the POST landed in storage (compare to creation_date for lag).

Operational order

1. Start with the latest report — do not guess a report id.
2. Read event and data.purchase.transaction (or data.subscription.subscriber.code) before summarizing.
3. List recent reports only for history, renewal chains, or duplicate-transaction checks.
4. Read ## This connection in the skill supplement for product- or funnel-specific field notes.

Gotchas

• Read-only — cannot approve, refund, cancel, or replay Hotmart events.
• Event vs purchase status — event is the webhook trigger; data.purchase.status is the transaction state (APPROVED, WAITING_PAYMENT, REFUNDED, DISPUTE, etc.).
• Subscription renewals — each renewal POSTs a purchase event with a new transaction and incremented recurrence_number; chain by subscriber.code.
• Missing buyer fields — checkout only returns data the buyer provided; absence is normal.
• Timestamps — creation_date and approved_date are milliseconds; order_date may be a string.
• Retries / duplicates — Hotmart may resend; compare id, transaction, and source.captured_at.
• Cart abandonment — PURCHASE_OUT_OF_SHOPPING_CART is a lead signal, not revenue; do not treat as an approved sale.