Summary webhooks

Summary webhooks reduce the size of invoice and subscription webhook payloads by sending a lightweight version of the core resource. When enabled, invoice payloads exclude line items and pricing details, and subscription payloads include only essential identification and status fields.

This feature is enabled per-account. Contact your Orb representative to enable summary webhooks for your account. All invoice and subscription webhook event types are affected when this feature is turned on.

Affected event types

Invoice events

The following invoice event types will send summary payloads when summary webhooks are enabled:

invoice.issued
invoice.edited
invoice.invoice_date_elapsed
invoice.issue_failed
invoice.payment_processing
invoice.payment_succeeded
invoice.payment_failed
invoice.manually_marked_as_paid
invoice.manually_marked_as_void
invoice.undo_mark_as_paid
invoice.sync_succeeded
invoice.sync_failed
invoice.accounting_sync_succeeded
invoice.accounting_sync_failed
invoice.dunning_schedule_created
invoice.dunning_schedule_ended
invoice.dunning_schedule_reset
invoice.dunning_schedule_step_executed

Subscription events

The following subscription event types will send summary payloads when summary webhooks are enabled:

subscription.created
subscription.edited
subscription.started
subscription.ended
subscription.plan_changed
subscription.plan_version_change_scheduled
subscription.plan_version_changed
subscription.fixed_fee_quantity_updated
subscription.usage_exceeded
subscription.cost_exceeded
subscription.trial_ended
subscription.plan_change_scheduled
subscription.cancellation_scheduled
subscription.cancellation_unscheduled
subscription.accounting_sync_succeeded
subscription.accounting_sync_failed

Invoice payload

Fields included

Field	Type	Description
`id`	string	Invoice ID
`invoice_number`	string	Auto-generated invoice number
`invoice_date`	datetime	The scheduled date of the invoice
`currency`	string	ISO 4217 currency string or `credits`
`status`	string	`draft`, `issued`, `paid`, `synced`, or `void`
`invoice_source`	string	`subscription`, `partial`, or `one_off`
`total`	string	Total after discounts and minimums
`amount_due`	string	Final amount to be charged
`due_date`	datetime	When payment is due
`customer`	object	Minified customer (`id`, `external_customer_id`)
`subscription`	object	Minified subscription (`id`)
`created_at`	datetime	When the invoice was created
`hosted_invoice_url`	string	Customer-facing invoice portal URL
`invoice_pdf`	string	Link to download the invoice PDF
`memo`	string	Free-form text on the invoice PDF
`will_auto_issue`	boolean	Whether the invoice will be automatically issued
`eligible_to_issue_at`	datetime	When the invoice becomes eligible to issue
`shipping_address`	object	Shipping address
`billing_address`	object	Billing address
`customer_tax_id`	object	Customer tax ID
`customer_balance_transactions`	array	Customer balance transactions
`credit_notes`	array	Associated credit note summaries
`payment_attempts`	array	Payment attempt history
`metadata`	object	Custom metadata
`issued_at`	datetime	When the invoice was issued
`paid_at`	datetime	When the invoice was paid
`voided_at`	datetime	When the invoice was voided
`scheduled_issue_at`	datetime	Scheduled issue time
`auto_collection`	object	Auto-collection configuration
`issue_failed_at`	datetime	When the invoice failed to issue
`sync_failed_at`	datetime	When external sync failed
`payment_failed_at`	datetime	Most recent payment failure time
`payment_started_at`	datetime	Most recent payment attempt start time

Fields excluded

The following fields are omitted from the summary invoice payload. Notably, line_items is the primary source of payload bloat for invoice webhooks.

Field	Type	Description
`line_items`	array	The full breakdown of prices
`subtotal`	string	Total before discounts and minimums
`discount`	object	Deprecated invoice-level discount
`discounts`	array	Invoice-level discounts
`minimum`	object	Invoice-level minimum
`minimum_amount`	string	Minimum amount
`maximum`	object	Invoice-level maximum
`maximum_amount`	string	Maximum amount

To retrieve the full invoice including line items, use the GET /invoices/{id} endpoint.

Subscription payload

Fields included

Field	Type	Description
`id`	string	Subscription ID
`name`	string	Subscription name
`status`	string	`active`, `ended`, or `upcoming`
`start_date`	datetime	When billing starts
`end_date`	datetime	When billing ends (null if ongoing)
`created_at`	datetime	When the subscription was created
`plan`	object	Plan summary: `id`, `external_plan_id`, `name`
`customer`	object	Customer summary: `id`, `external_customer_id`
`metadata`	object	Custom metadata

Fields excluded

The following fields are omitted from the summary subscription payload. The customer and plan fields are replaced with minified versions containing only identification fields.

Field	Type	Description
`current_billing_period_start_date`	datetime	Current billing period start
`current_billing_period_end_date`	datetime	Current billing period end
`trial_info`	object	Trial configuration
`active_plan_phase_order`	integer	Current plan phase
`fixed_fee_quantity_schedule`	array	Fixed fee quantity schedule
`default_invoice_memo`	string	Default memo for invoices
`auto_collection`	boolean	Auto-collection setting
`net_terms`	integer	Payment terms
`redeemed_coupon`	object	Coupon redemption
`billing_cycle_day`	integer	Billing cycle anchor day
`billing_cycle_anchor_configuration`	object	Billing cycle anchor config
`invoicing_threshold`	string	Invoicing threshold amount
`price_intervals`	array	Price intervals
`adjustment_intervals`	array	Adjustment intervals
`discount_intervals`	array	Discount intervals (deprecated)
`minimum_intervals`	array	Minimum intervals (deprecated)
`maximum_intervals`	array	Maximum intervals (deprecated)
`pending_subscription_change`	object	Pending subscription change

To retrieve the full subscription, use the GET /subscriptions/{id} endpoint.

Recommended integration pattern

With summary webhooks enabled, we recommend the following pattern for webhook handlers:

Receive the webhook event.
Read the event type and resource id from the payload.
Fetch the full resource via API if detailed data is needed.
Process accordingly.

This ensures your handler always acts on the most current state of the resource, avoiding issues with stale data in webhook payloads.

Even without summary webhooks, fetching the latest resource state via API before processing is a best practice. Webhook payloads represent the resource state at the time the event was emitted, which may differ from the current state if subsequent changes have occurred.

​Affected event types

​Invoice events

​Subscription events

​Invoice payload

​Fields included

​Fields excluded

​Subscription payload

​Fields included

​Fields excluded

​Recommended integration pattern

Affected event types

Invoice events

Subscription events

Invoice payload

Fields included

Fields excluded

Subscription payload

Fields included

Fields excluded

Recommended integration pattern