teachable-webhook
Teachable webhooks POST JSON when school events fire — sales, enrollments, subscription charges, refunds, user signups, and progress milestones. Each POST is one stored report. Inspect export.json on the latest delivery rather than assuming one fixed schema.
Payload envelope
Teachable commonly sends a JSON array with one event object (some schools enable “send as JSON array” in webhook settings). When the body is an array, read export.json[0] for the event; a bare object may appear if array mode is off.
Shared envelope fields on every event:
- type — event discriminator (e.g. Sale.created, Enrollment.created, Transaction.created).
- id — Teachable event id for this payload.
- hook_event_id — webhook firing id (use for dedupe alongside id).
- livemode — true for live school traffic.
- created — when Teachable created the event (ISO 8601); compare to source.captured_at for delivery lag.
- object — nested record; shape depends on type.
Missing upstream values arrive as JSON null.
Event types (common)
| type | Meaning |
|---|
| Sale.created | Product purchased or manual enrollment (free and paid; bundles = one sale) |
| Sale.subscription_canceled | Student canceled a subscription |
| Transaction.created | Charge succeeded (one-time or recurring billing cycle); excludes free / 100%-off coupon sales |
| Transaction.refunded | Charge refunded |
| Enrollment.created | Student enrolled in a course (each bundled course fires separately) |
| Enrollment.completed | Student finished 100% of a course |
| Enrollment.disabled | Student unenrolled (manual, failed payment, or access expiry) |
| User.created | New school account |
| User.updated | Profile change (new_name / old_name when name changed) |
| User.subscribe_to_marketing_emails / User.unsubscribe_from_marketing_emails | Marketing opt-in/out |
| UserTag.created / UserTag.removed | Tag added or removed |
| AbandonedOrder.created | Checkout abandoned (lead signal, not revenue) |
| LectureProgress.created | Lecture marked complete |
| Response.created | Graded quiz submitted |
| Comment.created | Course comment posted |
| EmailLead.created | Email lead form confirmed |
| Admission.created / Admission.disabled | Coaching service admission |
Key object fields by family
Sales (Sale.*) — object.id (sale id), object.user_id, object.school_id, object.price, object.final_price, object.currency, object.is_recurring, object.product (id, name, price, is_recurring), object.course (id, name, friendly_url), object.user (id, email, name, school_id, phone_number), optional object.coupon, object.affiliate, object.transactions[].
Transactions (Transaction.*) — object.id (transaction id), object.sale_id, object.user_id, object.school_id, object.final_price, object.net_charge, object.earnings_usd, object.amount_refunded, object.currency, object.status, object.is_recurring, object.purchased_at, nested object.sale (product/course/user context), optional Stripe charge details under object.data.
Enrollments (Enrollment.*) — object.id (enrollment id), object.user_id, object.course_id, object.sale_id, object.enrolled_at, object.percent_complete, object.is_active, nested object.user and object.course.
Users (User.*) — object.id, object.email, object.name, object.role, object.school_id, object.sign_in_count, object.unsubscribe_from_marketing_emails, object.phone_number.
Abandoned cart — object.user_email, object.main_product_name, object.main_product_price, object.checkout_url, object.order_token, optional object.order_bumps[].
Sale vs enrollment vs transaction
- Sale.created fires once per product purchase (a bundle counts as one sale).
- Enrollment.created fires per course — bundled products may produce several enrollment events for one sale.
- Transaction.created fires on each successful charge (including monthly subscription renewals); it does not fire for free enrollments or 100%-off coupons.
Chain recurring revenue with object.sale_id and transaction object.id, not sale id alone.
First moves
- Latest report — default for “what happened last” or “who bought or enrolled”.
- Read export.json[0].type (or top-level type when not wrapped) before interpreting nested fields.
- Recent reports — list when comparing renewals, refunds, duplicate webhook firings, or enrollment bursts from one bundle.
- One report by id — after listing, when the user names a specific stored delivery.
Response shape
- export.json — parsed webhook body (array or object).
- export.text — raw body when JSON is large or non-object.
- source.captured_at — when the POST landed here (use created inside JSON for upstream event time).
Operational order
- Start with the latest report — do not guess a report id.
- If captured_at is older than expected, say so — Teachable sends when the configured trigger fires, not on demand.
- List recent reports only for history, renewal chains, or duplicate suspicion.
- Read ## This connection in the skill supplement for school- or funnel-specific field notes.
Gotchas
- Read-only — cannot enroll students, issue refunds, or replay webhooks from here.
- Array wrapper — unwrap export.json[0] when the body is a one-element array.
- Duplicate firings — one purchase can produce Sale.created, multiple Enrollment.created, and Transaction.created; dedupe with hook_event_id, top-level id, and source.captured_at.
- Free vs paid — Sale.created includes free admin enrollments (final_price may be 0); Transaction.created only tracks paid charges.
- No purchaser IP on sales — Sale.created omits IP fields; enrollment events may include current_sign_in_ip on nested user.
- Legacy nulls — fields like last_four on enrollment user blocks are often always null; do not depend on them.
- Abandoned cart is not revenue — treat AbandonedOrder.created as a lead signal only.
