Webhook payload styles

Each webhook endpoint has a payload style, standard or expanded, that sets how much of a subscription or invoice its webhook events carry. Every payload names the style it was rendered in, in its payload_style field:

{
  "id": "o4mmewpfNNTnjfZc",
  "created_at": "2026-10-22T15:42:29+00:00",
  "type": "subscription.created",
  "payload_style": "standard",
  "subscription": { ... },
  "properties": {}
}

What a standard payload leaves out

In a standard payload, a subscription or invoice carries its own fields, with related objects as references. Everything an expanded payload computes on top of that is left out, so standard payloads stay small and quick to build however large the subscription or invoice grows.

In events about	Standard payloads carry	Left out
A subscription, such as `subscription.created`	`subscription` as a `SubscriptionSummary`: `id`, `name`, `status`, `start_date`, `end_date`, `created_at`, `metadata`, and the plan and customer as references	Price intervals, billing periods and the billing cycle anchor, plan phases, adjustment, discount, minimum and maximum intervals, the fixed fee quantity schedule, trial info, pending changes, redeemed coupons, invoicing threshold, net terms and auto-collection settings
An invoice, such as `invoice.issued`	`invoice` as an `InvoiceSummary`: every invoice field except those left out	Line items, `subtotal`, discounts, minimums and maximums

Every other event has the same payload in both styles. In the API reference, the page of each subscription or invoice event above links to its payload in the other style. When a handler needs something a standard payload leaves out, it can fetch the object by the id in the payload, with Fetch subscription or Fetch invoice. A fetched object reflects its current state, which may have changed since the event was created. An expanded payload carries each subscription or invoice in full, as the API returns it.

Default styles

New webhook endpoints use standard payloads unless you choose otherwise when you create them. Endpoints created before payload styles were introduced use expanded payloads until you change them.

Changing an endpoint’s style

Choose the style when you create or edit an endpoint in the webhooks portal, or set payload_style with Create webhook endpoint or Update webhook endpoint. A change applies to events created after it. Retries of an earlier event keep the style that event was created with, so an endpoint can receive payloads in both styles for a while after a change. A resend from the webhooks portal uses the endpoint’s current style when the event has a payload in it, and the event’s original style otherwise. Either way, payload_style says which style arrived. To move an endpoint from expanded to standard:

Update your handler to accept standard payloads. Fetch whatever it reads that standard payloads leave out.
Have the handler accept both styles, choosing by payload_style, since retries of earlier events keep arriving in the old style.
Change the endpoint’s style.

Parsing payloads with the SDKs

Orb’s SDKs have one parsing method per style. Verify each payload’s signature before acting on it.

SDK	Expanded payloads	Standard payloads
Python	`client.webhooks.unwrap(payload, headers)`	`client.webhooks.unwrap_standard(payload, headers)`
TypeScript	`client.webhooks.unwrap(payload, headers)`	`client.webhooks.unwrapStandard(payload, headers)`
Java and Kotlin	`client.webhooks().unwrap(payload, headers, secret)`	`client.webhooks().unwrapStandard(payload, headers, secret)`
Go	`client.Webhooks.Unwrap(payload)`	`client.Webhooks.UnwrapStandard(payload)`
Ruby	`client.webhooks.unwrap(payload)`	`client.webhooks.standard.unwrap_standard(payload)`

In Python, TypeScript, Java and Kotlin, both methods verify the signature with the endpoint’s secret (the client’s webhook secret unless you pass one). They raise an error, naming the method to use, when a payload’s payload_style is the other style. A payload without payload_style, from before payload styles were introduced, reads as expanded. In Go and Ruby, the methods only parse. In Go, call client.Webhooks.VerifySignature first; in Ruby, verify the signature yourself. Outside Ruby, the standard method is an alias for the standard subresource’s method, which works the same way: webhooks.standard.unwrap_standard in Python, webhooks.standard.unwrapStandard in TypeScript, webhooks().standard().unwrapStandard in Java and Kotlin, and Webhooks.Standard.UnwrapStandard in Go. The C# SDK doesn’t have typed webhook parsing; verify the signature and deserialize the payload yourself. A Python handler that accepts both styles while an endpoint changes over:

import json

from orb import Orb

client = Orb()  # reads ORB_API_KEY and ORB_WEBHOOK_SECRET


def handle_webhook(body: str, headers: dict[str, str]) -> None:
    if json.loads(body).get("payload_style") == "standard":
        event = client.webhooks.unwrap_standard(body, headers)
    else:
        event = client.webhooks.unwrap(body, headers)
    ...

unwrap and unwrap_standard verify the signature before parsing, so reading payload_style from the unverified body only picks the method.

​What a standard payload leaves out

​Default styles

​Changing an endpoint’s style

​Parsing payloads with the SDKs

What a standard payload leaves out

Default styles

Changing an endpoint’s style

Parsing payloads with the SDKs