Paddle Webhook

Paddle Webhook

Each stored delivery is one Paddle Billing notification — a single JSON object POSTed when an event occurs in the connected account. The envelope is always the same: event_id, event_type, occurred_at, notification_id, and a data snapshot of the entity that changed. Tools read what already landed; there is no pull API and no way to replay, acknowledge, or mutate Paddle state from here.

Paddle Billing vs Paddle Classic

This skill describes Paddle Billing notifications (current default for new accounts). Billing payloads use event_type in entity.action form (for example transaction.completed, subscription.created) and prefixed ids (evt_, ntf_, txn_, sub_, ctm_).

Paddle Classic is a different system: webhooks identify events with alert_name (for example subscription_created, payment_succeeded) and a flat, legacy field layout — not the Billing envelope above. If export.json has alert_name instead of event_type, treat it as Classic and read that schema; do not assume Billing field names.

First moves

1. Latest report — default for “what billing event happened last”.
2. Read export.json.event_type — classify before quoting money, subscription status, or customer ids.
3. Recent reports — scan history when deduping retries, tracing checkout, or comparing subscription lifecycle events.
4. One report by id — after listing, when the user points at a specific delivery.

Envelope fields (export.json)

• event_type — dotted name in entity.action format; primary router (transaction.paid, subscription.canceled, customer.created, adjustment.created, etc.).
• event_id — stable event id (evt_…); dedupe key for at-least-once delivery and automatic retries.
• occurred_at — RFC 3339 time the event happened upstream; use for ordering when events arrive out of sequence.
• notification_id — delivery attempt id (ntf_…); changes on replays and separate destinations — not a dedupe key.
• data — entity snapshot at event time; shape depends on event_type prefix.

Event classification

Transaction events (event_type starts with transaction.)

Common types: transaction.created, transaction.ready, transaction.paid, transaction.completed, transaction.billed, transaction.updated, transaction.canceled, transaction.past_due, transaction.payment_failed, transaction.revised.

Useful data fields when present:

• Identity — id (txn_…), status (draft, ready, paid, completed, billed, canceled, past_due).
• Links — customer_id (ctm_…), address_id, business_id, subscription_id (sub_…), discount_id.
• Money — details.totals (subtotal, tax, discount, grand_total, fee, earnings, currency_code); amounts are strings in the lowest currency unit (cents for USD).
• Line items — items[] with price, product, quantity, nested price.unit_price.
• Payments — payments[] with method, status, and captured amounts after transaction.paid.
• Passthrough — custom_data on the transaction or line items when set at checkout.

Checkout sequence (typical): transaction.created → customer.created / address.created / business.created during checkout → transaction.paid (payment captured) → subscription.created for recurring items → transaction.completed (fees, invoice numbers, subscription linkage finished). Use transaction.paid for earliest paid signal; transaction.completed for fully processed revenue records.

Subscription events (event_type starts with subscription.)

Common types: subscription.created, subscription.trialing, subscription.activated, subscription.updated, subscription.paused, subscription.resumed, subscription.past_due, subscription.canceled, subscription.imported.

Useful data fields when present:

• Identity — id (sub_…), status (active, trialing, canceled, past_due, paused).
• Customer — customer_id, address_id, business_id.
• Billing — currency_code, billing_cycle (interval, frequency), started_at, first_billed_at, next_billed_at, canceled_at.
• Items — items[] with linked price and product ids.
• Checkout link — transaction_id appears on subscription.created only (ties the new subscription to the checkout transaction); other subscription events omit it.
• Passthrough — custom_data.

Other entity groups (less common on ingest connections but valid event_type values)

• Customer / address / business — customer.created, address.updated, business.created, etc.; data.id is the entity id, often with email, name, or address fields.
• Adjustments — adjustment.created, adjustment.updated for refunds, chargebacks, credits; inspect action, status, and linked transaction ids.
• Catalog / ops — product.*, price.*, discount.*, payout.*, report.*, payment_method.*, api_key.* when subscribed.

Response shape

• export.json — parsed notification body; start with event_type, event_id, and data.
• export.text — raw body when JSON is large or parsing failed.
• source.captured_at — when the POST landed here; compare with occurred_at for ordering and freshness.

Operational order

1. Start with the latest report — do not guess a report id.
2. State event_type and read data.status (for transactions/subscriptions) before summarizing revenue or access changes.
3. If captured_at is older than expected, say so — notifications arrive on upstream events, not on demand.
4. List recent reports only for history, duplicate suspicion, checkout tracing, or explicit compare-by-date asks.
5. Read ## This connection in the skill supplement for product- or environment-specific field notes.

Gotchas

• Read-only — cannot refund, cancel subscriptions, replay notifications, or change Paddle settings from here.
• Billing vs Classic — mismatched schemas break field assumptions; check for event_type vs alert_name first.
• At-least-once delivery — Paddle retries until HTTP 200 within five seconds; dedupe on event_id, not notification_id or captured_at.
• Out-of-order events — compare occurred_at when subscription.updated and subscription.canceled disagree; do not assume arrival order equals lifecycle order.
• One event per POST — unlike batched providers, each delivery is a single notification, not an array of unrelated events.
• Paid vs completed — transaction.paid confirms capture; transaction.completed adds fees, earnings, invoice numbers, and subscription creation side effects.
• Amount encoding — totals in details.totals are string minor units; divide by 100 for USD dollars unless the user asked for cents.
• Partial snapshots — data is the entity at event time; customer email and line-item detail may require correlating multiple recent deliveries (customer.* plus transaction.*).
• Sandbox vs live — infer from data.custom_data, product/price ids, or dashboard context; there is no single universal live flag on every event type.
• Empty — no stored reports means nothing has arrived yet; say no webhook is available.