Storyboard / SDK skill on-ramp inventory: HMAC vs RFC 9421

[EvgenyAndroid]

Companion to #4205 — taking the storyboard / SDK skill on-ramp pass I self-pledged ("inventory which currently reference HMAC vs RFC 9421 and file a follow-up issue").

Framing

Per @bokelley's reframe in #4205: the right metric isn't "% migrated" against the installed base (which is ~empty). It's "no new HMAC implementers after date X," enforced via four on-ramp surfaces:

• docs (docs: add RFC 9421 request signing guide #3064)
• grade tooling (Grade tools: add OAuth and request signing setup evaluation #3360)
• SDK ✅ (already done)
• storyboards / agent on-ramp skills ← this issue

This issue covers surface 4. Where SDK-bundled skills + storyboard-adjacent compliance / schema docs frame webhook auth, do they steer new buyers toward 9421 or do they leave HMAC as the path of least resistance?

Inventory (against adcp-3.0.8)

✅ Already well-framed (no action)

Surface	Treatment
compliance/universal/webhook-emission.yaml	Calls HMAC "deprecated fallback"; grades 9421 as default; legacy buyers graded only on idempotency phases.
compliance/universal/signed-requests.yaml	RFC 9421 only; no HMAC mention.
compliance/test-vectors/webhook-signing/README.md	RFC 9421 throughout; production keys MUST be minted under own jwks_uri.
schemas/3.0.8/core/push-notification-config.json	"By default, webhooks are signed with the AdCP RFC 9421 profile"; auth block is the deprecated fallback, removed in 4.0. Best-in-class framing.

🟡 Stale framing — actively recommends HMAC

schemas/3.0.8/core/reporting-webhook.json

Line 24 description on the authentication block:

Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)

This contradicts push-notification-config.json's framing (HMAC is the deprecated fallback there). Two adjacent webhook config schemas tell new buyers different things. Worse, on this schema authentication is required (line 63) — there is no path to opt into 9421 for reporting webhooks at all.

Suggested fix: align with push-notification-config.json's description; make authentication optional and document that omitting it selects the default 9421 profile (or document why reporting webhooks are different and intentionally locked to legacy).

schemas/3.0.8/enums/auth-scheme.json

Enum is [\"Bearer\", \"HMAC-SHA256\"] with a description that doesn't mention deprecation. A buyer reading this enum in isolation has no signal these are legacy options. Suggested fix: extend the description to note these are legacy auth-block options for buyers who haven't adopted the default 9421 webhook profile.

🔴 Silent — agent on-ramp skills don't mention webhook auth at all

The skills/*/SKILL.md files are what SDKs ship to teach LLM agents the wire contract. They cover idempotency_key, the oneOf account discriminator, async status:'submitted' polling, error recovery from adcp_error.issues[] — but none of them mention webhook signing:

• skills/call-adcp-agent/SKILL.md (cross-cutting buyer-side basics) — zero webhook auth references
• skills/adcp-signals/SKILL.md — only "Poll or use webhooks to check completion status" (line 178); no auth guidance
• skills/adcp-media-buy/SKILL.md — only "Poll or use webhooks to check completion status" (line 392); no auth guidance
• skills/adcp-creative/SKILL.md — no webhook references
• skills/adcp-governance/SKILL.md — no webhook references

A new buyer agent built from these skills will reach for push_notification_config.authentication (the visible field in the schema) before learning that omitting it selects the modern path. The on-ramp surface that matters most for "no new HMAC implementers" is silent on the choice.

Suggested fix: a short section in call-adcp-agent/SKILL.md (cross-cutting, all buyer agents load this first) titled e.g. "Webhook signing — default to RFC 9421":

• Default behavior: omit push_notification_config.authentication → seller signs with 9421 against the JWKS published at its brand.json agents[].jwks_uri
• Buyer verifies via the published JWKS; no shared secret crosses the wire
• Legacy authentication block (Bearer / HMAC-SHA256) is the deprecated fallback for receivers that haven't adopted 9421; removed in AdCP 4.0
• Link to docs/building/implementation/security.mdx#webhook-callbacks for full profile + verifier checklist

That single section closes the silent-default trap across all five protocol skills, since they all > Buyer-side basics ... live in skills/call-adcp-agent/SKILL.md.

Out of scope

• schemas/core/assets/webhook-asset.json (DCO outbound webhook, separate auth model — webhook-security-method.json enum: hmac_sha256/api_key/none). Different surface, not part of buyer push-notification webhooks.
• Live docs at adcontextprotocol.org/docs/building/implementation/security.mdx — those are tracked under docs: add RFC 9421 request signing guide #3064 (docs default to RFC 9421) and out of scope here. This issue scoped to bundled storyboard / SDK skill / schema descriptions only.

Suggested resolution

Two-PR shape:

1. Schema PR — fix reporting-webhook.json description (and consider making authentication optional with 9421 default); add a deprecation hint in auth-scheme.json enum description.
2. SDK skill PR — add a webhook-signing section to skills/call-adcp-agent/SKILL.md so all five protocol skills inherit the framing.

Happy to take a first pass on either if a maintainer wants to triage rough scope first.

References

• [meta] Coordinate RFC 9421 webhook signing migration — adoption telemetry + threshold + ownership #4205 (parent — RFC 9421 webhook signing migration coordination)
• [meta] JWKS adoption baseline gates signal-payment chain-of-custody work (Track A.0) #4206 (companion — Track A.0 JWKS adoption baseline)
• docs: add RFC 9421 request signing guide #3064 (docs surface)
• Grade tools: add OAuth and request signing setup evaluation #3360 (grade tooling surface)
• adcp-client SDK migration (already shipped in @adcp/sdk 5.25.0)

Filed by an agent vendor consuming the bundled adcp-3.0.8 skills + schemas; happy to discuss what "agent on-ramp" reads like from the consumer side.

[bokelley]

Triage

Classification: Bug (stale framing) + Doc improvement (on-ramp skill gap)
Bucket(s): spec / protocol, web / site / docs
Status: drafting-pr (partial) + ready-for-human (signing-profile items)

What the experts said:

• ad-tech-protocol-expert: reporting-webhook.json and auth-scheme.json descriptions demonstrably contradict the normative security doc and push-notification-config.json; description-only fixes are patch-eligible on 3.0.x; making authentication optional is a signing-profile change — never patch-eligible, routes to 3.1.x as minor
• docs-expert: SKILL.md addition closes the silent-default trap; "switch, not fallback" is the key framing; placement under "Non-obvious rules" is correct; link path and key-publication doc (brand.json per security.mdx §webhook-callbacks) corrected through two fix iterations
• code-reviewer: all blockers resolved after second pass; JSON valid; patch changeset correct

My take: Three surfaces ship in PR #4271. Two items need a human call before code can land.

Shipped in #4271: reporting-webhook.json description (removed "recommended for production" for HMAC; noted field required in 3.x, removed in 4.0), auth-scheme.json deprecation note, call-adcp-agent/SKILL.md webhook-signing section.

Remaining in this issue:

• authentication optional in reporting-webhook.json — removing from required[] is a signing-profile change (playbook: never patch-eligible). Needs minor bump + security doc explicitly covering reporting_webhook signing-mode selection. @bokelley, your call: (A) extend security.mdx §webhook-callbacks to include reporting_webhook and land in 3.1.x, or (B) document that reporting webhooks are intentionally locked to legacy auth in 3.x with 4.0 removal as the only on-ramp.
• artifact_webhook in create-media-buy-request.json — same stale "recommended for production" framing found by protocol-expert; excluded from fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md #4271 to keep diff bounded; same description fix applies.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01WczUEAGjbrADfTVX2MWEn6

---

Generated by Claude Code

[EvgenyAndroid]

First-pass schema-fix PR opened: #4273 — covers the description-only edits on reporting-webhook.json (drop the "recommended for production" line on HMAC-SHA256) and auth-scheme.json (deprecation framing in the enum description). Mirrors precedent #2506.

Structural piece (drop \"authentication\" from reporting-webhook.json's required: [...] so reporting webhooks have an opt-in path to RFC 9421) is held back as a separate normative question — happy to follow up with that PR if maintainers triage favorably.

Skill section (skills/call-adcp-agent/SKILL.md webhook-signing on-ramp) is the third piece; will sequence after maintainer signal on the schema PR.

[bokelley]

Triage

Classification: Blocker update
Status: ready-for-human

New blocker since prior triage: @EvgenyAndroid opened PR #4273 covering the same reporting-webhook.json and auth-scheme.json description edits already in the bot-drafted #4271. Two PRs now compete for the same surface.

Two issues to reconcile:

1. Duplicate scope — fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md #4271 and schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 #4273 will conflict on merge.
2. Wrong base branch in schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 #4273 — description-only schema fixes are patch-eligible per the playbook and route to 3.0.x. fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md #4271 already targets 3.0.x correctly; schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 #4273 targets main.

Your call, @bokelley: Close #4273 and proceed with #4271 (more complete — also includes the call-adcp-agent/SKILL.md addition — and correctly targeted to 3.0.x), or close #4271 and let @EvgenyAndroid retarget #4273 to 3.0.x and add the SKILL.md section. Either way, one needs to close before either can merge cleanly.

The normative question from the prior triage (making authentication optional in reporting-webhook.json) is unaffected — still waiting on your Option A / B call regardless of which PR proceeds.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01TQMTU3Q7CnPKFXbzUYxVyJ

---

Generated by Claude Code

[EvgenyAndroid]

Second leg opened: #4275 — adds a webhook-signing on-ramp section to skills/call-adcp-agent/SKILL.md so all five protocol skills inherit the 9421 default framing. Independent of #4273; either order lands fine.

[bokelley]

Triage

Classification: Blocker update
Status: ready-for-human (updated)

PR #4275 now open for the call-adcp-agent/SKILL.md portion — the same surface #4271 already covers. This extends the prior decision tree:

• Proceed with fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md #4271 (atomic, correctly targeted to 3.0.x): close both schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 #4273 and skills(call-adcp-agent): document RFC 9421 as default webhook signing path #4275.
• Proceed with @EvgenyAndroid's PRs: retarget schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 #4273 to 3.0.x, keep skills(call-adcp-agent): document RFC 9421 as default webhook signing path #4275, close fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md #4271.

No change to the unresolved normative question (making authentication optional in reporting-webhook.json).

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01HBhGAHrQ78RHXfqGhbE8xX

---

Generated by Claude Code