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.issuedinvoice.editedinvoice.invoice_date_elapsedinvoice.issue_failedinvoice.payment_processinginvoice.payment_succeededinvoice.payment_failedinvoice.manually_marked_as_paidinvoice.manually_marked_as_voidinvoice.undo_mark_as_paidinvoice.sync_succeededinvoice.sync_failedinvoice.accounting_sync_succeededinvoice.accounting_sync_failedinvoice.dunning_schedule_createdinvoice.dunning_schedule_endedinvoice.dunning_schedule_resetinvoice.dunning_schedule_step_executed
Subscription events
The following subscription event types will send summary payloads when summary webhooks are enabled:
subscription.createdsubscription.editedsubscription.startedsubscription.endedsubscription.plan_changedsubscription.plan_version_change_scheduledsubscription.plan_version_changedsubscription.fixed_fee_quantity_updatedsubscription.usage_exceededsubscription.cost_exceededsubscription.trial_endedsubscription.plan_change_scheduledsubscription.cancellation_scheduledsubscription.cancellation_unscheduledsubscription.accounting_sync_succeededsubscription.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 |
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 |
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.
