feat(webhooks): webhook_activity[] on get_media_buys + standardized log surface (#4278, #4582 track 4)

[bokelley]

Summary

Buyer-side webhook delivery visibility for AdCP 3.1 — closes the operator-ticket loop for "did the publisher fire? did my endpoint receive it? was the retry trail clean?" Lands as two request fields + one response field on get_media_buys, with the canonical record + truncation sentinel + pattern documentation that #4582 track 4 generalizes from this seed.

Closes #4278. Lands #4582 track 4.

What changed

Schema additions:

• get-media-buys-request.json — include_webhook_activity (bool, default false), webhook_activity_limit (int 1–200, default 50)
• get-media-buys-response.json — webhook_activity[] (maxItems 200, items $ref the canonical record)
• NEW /schemas/core/webhook-activity-record.json — canonical record shape (95 lines). Top-level additionalProperties: false with ext escape — deliberate departure from convention to enforce uniform-across-resources at the schema level. Nullable fields use draft-07 union types.
• NEW /schemas/core/truncation-sentinel.json — universal _meta.truncated sentinel (42 lines). No field consumes it today; lands for future include_webhook_payloads extension. Open preview_format, _meta.additionalProperties: true for forward-compat.

Normative resolutions (resolves #4278 RFC open questions):

• Retention is MUST 30 days from completed_at uniformly across success/failed/timeout/connection_error. Pending records run from fired_at until termination, then transition. Sellers unable to honor MUST omit the field entirely via the three-state semantics.
• Three-state presence: omitted = seller does not surface; [] = persists but no recent fires; non-empty = actual records. Buyers diagnose omissions via push_notification_config registration state + propagation_surfaces capability declaration.
• idempotency_key not delivery_id — equals the webhook payload's dedup key, so buyers correlate to their endpoint logs without a join table.
• Status enum — 5 values incl. pending (not retrying — outcome-noun vocabulary). timeout / connection_error split is operationally distinct and intentional.
• URL — query string and fragment MUST be stripped; secret-shaped path segments SHOULD be redacted.
• error_message — server-side classification only; never request/response bodies or headers; reserved for future include_webhook_payloads.
• subscriber_id reserved on the canonical record for multi-subscriber configurations (precedent: 4.0: multi-subscriber reporting_webhook on media buys #3009).

Documentation:

• docs/protocol/snapshot-and-log.mdx — new normative § Webhook activity log pattern with a 7-item adoption checklist so future consumers (Creative lifecycle webhooks: formalize state-change notifications outside media buy lifecycle #2261 creative lifecycle, RFC: Webhook foundation for AdCP (epic) #4582 track 3 per-account reads in 3.2) have unambiguous MUST hooks.
• docs/building/by-layer/L3/webhooks.mdx — "Diagnosing missing fires" subsection back-linking to the call site.
• docs/media-buy/task-reference/get_media_buys.mdx — full call-site documentation, status semantics, three-state presence, retention rule, privacy rules, omission diagnosis, JS/TS + Python example using the canonical WebhookActivityRecord type that the SDK regenerates from /schemas/core/.

#4582 epic scope

• Track 1 (snapshot/log duality doc) — already shipped on main; extended here with the pattern section.
• Track 2 (persistent webhook contract, incl. auth renewal) — already shipped on main; back-link added.
• Track 3 (per-account subscription model) — explicitly deferred to 3.2.0 to compose with 4.0: multi-subscriber reporting_webhook on media buys #3009 multi-subscriber direction. Consumers (Creative lifecycle webhooks: formalize state-change notifications outside media buy lifecycle #2261, Org-level notification webhooks for compliance alerts #1711, RFC: Dependency Impact & Health Notifications (epic) #2853) can use per-resource push_notification_config in 3.1 and adopt account-level in 3.2.
• Track 4 (standardized log surface) — shipped here.
• Tracks 5–7 (auth/transport hygiene, dedup edge cases, conformance) — separate cadence per the epic.

Review history

Two parallel expert review passes (dx-expert + ad-tech-protocol-expert) on the basic #4278 surface, then a second parallel pass on the track-4 generalization, then a final consistency check (code-reviewer) before commit. Fixes applied across:

• delivery_id → idempotency_key (eliminates join-table footgun)
• status: retrying → status: pending (outcome-noun consistency with Stripe/Segment)
• notification_type keeps full enum incl. impairment (same debug contract for delivery + health fires)
• additionalProperties: false on record items (stable contract, no smuggling)
• subscriber_id framing portable across resources (not media-buy-specific)
• Retention pivot: fired_at → completed_at with pending carve-out (retries don't age out mid-trail)
• preview_format opened from closed enum → open string with five common values
• _meta.additionalProperties: true for sentinel forward-compat
• "MUST follow verbatim" → explicit 7-item adoption checklist
• Three-state cardinality universal; omission causes resource-specific
• WebhookActivityRecord shown via type import in examples; SDK regen-required noted
• maxItems: 200 on response array (structural enforcement of the request cap)
• All nullable: true (OpenAPI shorthand) replaced with draft-07 union types ("type": ["string", "null"])
• TypeScript fence labeled correctly on the typed example
• Retention rule clarified to cover timeout / connection_error outcomes explicitly

Test plan

• npm run build:schemas — clean, $ref resolves in bundled output
• npm run test:schemas — 7/7
• npm run test:composed — 43/43
• npm run test:json-schema — 260/260
• npm run test:examples — 36/36
• Precommit hooks (test:unit + typecheck) — clean
• Visual review of rendered MDX (check the pattern doc cross-link, the call-site cross-link, the diagnosis paragraph)
• Optional: rebuild @adcp/sdk and verify WebhookActivityRecord exports as expected before merge — affects only the example imports, not the spec correctness

🤖 Generated with Claude Code

[bokelley]

Re-scoping note before this merges: I want to reverse the track-3 deferral and land per-account subscription in 3.1 alongside #2261, not 3.2.

Reasoning: creative lifecycle is the only consumer with no workable per-resource anchor in 3.1. #2853 (dependency impact) and #1711 (compliance) can limp on per-buy push_notification_config; creatives genuinely can't (sync_creatives task webhooks are scoped to the sync operation, not creative-as-resource). Forcing track 3 through a real consumer is how we avoid the abstract-by-committee drift that #4588 successfully dodged.

#3009 composition still works — per-account anchor and multi-subscriber are orthogonal axes. Ship per-account-single-subscriber in 3.1 with subscriber_id already reserved on webhook_activity_record (this PR); #3009 adds the multi-subscriber dimension to either anchor later.

This doesn't block #4701 — track 4 still ships here. Just want to remove the "track 3 → 3.2.0" framing from the PR body before merge, and pull #2261 into 3.1.0 as the proving ground.