docs: webhook fan-out reference + metadata correlation guide

[next-devin]

Summary

Two additions to help external developers self-serve on common integration questions surfaced via support inquiries:

1. webhooks/index.mdx — new sections on event trigger sources and rebill identification
2. admin-api/guides/metadata-and-correlation.mdx — new guide on the canonical metadata patterns, including cross-rebill correlation via `attribution.metadata`

What's in each file

content/docs/webhooks/index.mdx

§ Event Trigger Sources — most `*.updated` events fan out across multiple sender models, not just the headline resource. The new table lists every model whose change fires each event (e.g., `order.updated` fires on Order, Line, Transaction, Refund, MarketingAttribution, ShippingAddress, BillingAddress, Fulfillment, plus tag changes). Picking the leanest event for a use case is currently institutional knowledge; this surfaces it.

Includes a callout recommending `transaction.created` filtered to `type: "debit"` as the leanest signal for "fulfill on charge."

§ Identifying Rebill Orders — explains how to distinguish renewal orders from new-customer orders:

• On `order.created`: check the `subscriptions` block / `subscription_lifecycle` field
• On `transaction.created`: the inline `subscription` block contains `id` + `billing_cycle`, where `billing_cycle` is the integer cycle counter (0 = initial, 1 = first rebill, etc.)

content/docs/admin-api/guides/metadata-and-correlation.mdx (new)

• § Supported Objects — explicit list of the 9 `Definition.TYPE_CHOICES` values (`attribution`, `customer`, `dispute`, `line`, `order`, `product`, `variant`, `blog`, `page`) with a callout that subscriptions and carts are not directly metadata-managed
• § Setting and Reading Metadata — basic PATCH example for setting custom fields on a supported object
• § Cross-Rebill Correlation via Attribution — the canonical pattern walkthrough using a `plan_id` example:
  1. Define attribution metadata field via `metadataCreate`
  2. PATCH the subscription with `attribution.metadata`
  3. Receive it inline on `subscription.updated`, `order.created` (incl. renewals), `transaction.created` — with worked JSON payload excerpt
• § When to Use Which Surface — decision table for picking the right metadata field for common needs

Why now

Surfaced via merchant inquiry from a customer building integration to an external plan-management service. The conversation took multiple rounds to produce an authoritative answer because the canonical pattern (`attribution.metadata` rebill inheritance) wasn't documented anywhere public, the metadata-managed object list was buried inside the Metadata API enum, and event fan-out semantics were institutional knowledge. This PR puts all three into the docs so the next developer asking the same question gets the answer on first read.

Test plan

• Visual review of the rendered `webhooks/index.mdx` (new sections appear between events table and "Webhook Data Structure")
• Visual review of the new guide in the Admin API > Guides sidebar (slotted between "Subscription Management" and "Exports")
• Verify all internal links resolve (`#cross-rebill-correlation-via-attribution`, `/docs/admin-api/reference/metadata/metadataCreate`)
• Spot-check the worked JSON payload examples render cleanly under fumadocs syntax highlighting

🤖 Generated with Claude Code

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Other Observations (not in diff)

One item noted for awareness:

File	Line	Issue
content/docs/webhooks/index.mdx	97	product.updated row uses "AttributeOption*" with an asterisk. This is an informal notation; verify it accurately represents the actual model naming used by the codebase.

Files Reviewed (3 files)

• content/docs/admin-api/guides/meta.json - Addition of new page entry
• content/docs/admin-api/guides/metadata-and-correlation.mdx - New guide (132 lines)
• content/docs/webhooks/index.mdx - New sections: Event Trigger Sources table (lines 74-104), Identifying Rebill Orders (lines 106-125)

Reviewer Notes:

The PR adds two valuable documentation improvements: (1) an "Event Trigger Sources" table clarifying the fan-out behavior of *.updated events, which is currently institutional knowledge, and (2) a new Metadata & External Correlation guide covering the canonical pattern for cross-rebill correlation via attribution.metadata. Both additions address real support pain points identified in the PR description.

The changes are accurate, well-structured, and follow existing documentation patterns. The internal links (#cross-rebill-correlation-via-attribution, /docs/admin-api/reference/metadata/metadataCreate) and sidebar placement appear correct.

---

_{Reviewed by minimax-m2.7 · 315,002 tokens}