Chargebee Webhook

Chargebee Webhook

Each stored delivery is one Chargebee event POST — a single JSON Event envelope. Chargebee fires one event per notable change (subscription lifecycle, invoice, payment, customer update). Tools read what already landed; there is no pull API and no way to replay, acknowledge, or mutate billing state from here.

First moves

1. Latest report — default for “what billing event happened last”.
2. Read export.json.event_type — classify the event before walking nested resources.
3. Walk export.json.content — resource keys present depend on event_type (subscription, customer, invoice, transaction, etc.).
4. Recent reports — scan history when deduping retries, comparing MRR signals, or tracing a customer across events.
5. One report by id — after listing, when the user points at a specific capture.

Event envelope

Every POST body is one Event object. Start with top-level fields:

• id — unique event id (dedupe key for retries and manual resends).
• event_type — snake_case lifecycle signal (see categories below).
• occurred_at — UTC seconds when the change happened (not the same as source.captured_at).
• api_version — Chargebee API version used to render content (v1 or v2); field shapes differ by site configuration.
• source — what triggered the event (api, admin_console, scheduled_job, hosted_page, external_service, etc.).
• object — always "event".
• content — JSON object holding one or more resource snapshots keyed by resource name.
• user — who triggered the event when present (admin email, API key name, service name).
• webhook_status, webhook_failure_reason, webhooks — delivery metadata on some events; usually omit for business summaries.

Idempotency and retries

Chargebee retries failed webhook calls up to seven times over roughly two days (last retry around 3 days 7 hours after the original trigger). The same id resends with an identical payload — dedupe on id when counting unique events across stored deliveries. Manual resend from the Chargebee console also reuses the same event id. Webhooks may arrive out of order; content is a point-in-time snapshot that does not update on retries.

content object — resource keys

Inspect which keys exist under content before quoting fields. Common keys by category:

Key	Typical events
subscription	subscription_* lifecycle (created, activated, changed, cancelled, renewed, paused, …)
customer	customer_* and many subscription/invoice events
invoice	invoice_*, pending_invoice_*, payment-linked billing
transaction	transaction_*, payment_* success/failure/refund
credit_note	credit_note_* refunds and adjustments
card, payment_source	payment method add/update/delete
coupon, item, item_price	catalog and promotion changes
quote, order, unbilled_charge	quotes, one-time orders, unbilled usage

Resource field names follow the Chargebee REST API for the site’s api_version — do not assume v1 plan/addon shapes on a v2 Product Catalog site (or vice versa). Read what the latest JSON actually contains.

Common event_type values

Subscription lifecycle — subscription_created, subscription_started, subscription_activated, subscription_changed, subscription_renewed, subscription_cancelled, subscription_cancellation_scheduled, subscription_reactivated, subscription_deleted, subscription_paused, subscription_resumed, subscription_trial_end_reminder, subscription_trial_extended, subscription_renewal_reminder.

Customer — customer_created, customer_changed, customer_deleted, customer_moved_out, customer_moved_in.

Invoice — invoice_generated, invoice_updated, invoice_deleted, pending_invoice_created, pending_invoice_updated.

Payments and transactions — payment_succeeded, payment_failed, payment_refunded, payment_initiated, transaction_created, transaction_updated, transaction_deleted.

Credit notes — credit_note_created, credit_note_updated, credit_note_created_with_backdating.

Payment sources — payment_source_added, payment_source_updated, payment_source_deleted, card_added, card_updated, card_deleted, card_expiring, card_expired.

Useful fields inside content

content.subscription (when present)

• Identity — id, customer_id, plan_id / subscription_items[] (v2 catalog).
• State — status (active, in_trial, non_renewing, paused, cancelled, …), billing_period, billing_period_unit.
• Money — plan_amount, plan_unit_price, mrr, currency fields on nested items.
• Timing — created_at, activated_at, current_term_start, current_term_end, next_billing_at, trial_end, cancelled_at.
• Trial — trial_start, trial_end, has_scheduled_changes.

content.customer (when present)

• Identity — id, email, first_name, last_name, company, phone.
• Billing — auto_collection, preferred_currency_code, billing_address, taxability.
• Meta — created_at, updated_at, custom fields under cf_* or custom_fields.

content.invoice (when present)

• Identity — id, customer_id, subscription_id.
• State — status (paid, payment_due, not_paid, voided, …), recurring.
• Money — total, amount_paid, amount_due, sub_total, tax, currency_code, line_items[].
• Timing — date, due_date, paid_at.

content.transaction (when present)

• Identity — id, customer_id, subscription_id, invoice_id.
• State — status, type (payment, refund, …), payment_method.
• Money — amount, currency_code.

Response shape

• export.json — parsed Event envelope; start with event_type, id, and content.
• export.text — raw body when JSON is large or parsing failed.
• source.captured_at — when the POST landed here; compare with occurred_at for delivery lag.

Operational order

1. Start with the latest report — do not guess a report id.
2. State event_type and top-level id before summarizing nested resources.
3. If captured_at is older than expected, say so — Chargebee delivers asynchronously and retries on non-2xx responses.
4. List recent reports only for history, duplicate suspicion, or tracing a subscription/customer across time.
5. Read ## This connection in the skill supplement for site-specific plan ids or custom field notes.

Gotchas

• Read-only — cannot create subscriptions, issue refunds, or acknowledge webhooks upstream.
• One event per POST — unlike batched webhook providers, each delivery is a single Event object.
• Dedupe on id — retries and manual resends reuse the same event id; do not double-count across captures.
• Out-of-order delivery — a newer subscription_changed may arrive before an older invoice_generated; use occurred_at and event id history, not arrival order alone.
• Snapshot vs live state — content reflects the resource immediately after the change; for current state an agent would need the Chargebee API (separate connection), not ingest alone.
• api_version shapes — v1 sites use plan/addon fields; v2 Product Catalog sites use item/item_price/subscription_items — inspect the latest JSON.
• Card data masked — payment source objects typically omit full PAN/CVV.
• Empty — no stored reports means nothing has arrived yet; say no webhook is available.