skills(call-adcp-agent): document RFC 9421 as default webhook signing path#4275
Closed
EvgenyAndroid wants to merge 1 commit intoadcontextprotocol:mainfrom
Closed
Conversation
… path The five protocol skills all delegate cross-cutting buyer-side basics to call-adcp-agent/SKILL.md. That skill was silent on webhook signing, leaving SDK consumers with no signal that omitting push_notification_config.authentication selects the modern RFC 9421 path — a new buyer reading the schema sees a visible authentication field and reaches for it. Adds a "Webhook signing — default to RFC 9421, don't reach for authentication" section to the cross-cutting skill, mirroring the framing locked in by adcontextprotocol#2506 on push-notification-config.json: - Default 9421 path (seller publishes JWKS at brand.json agents[].jwks_uri, buyer verifies — no shared secret on the wire) - Switch-not-fallback rule: presence of authentication selects legacy; absence selects 9421 - Inbound verifier checklist: required covered components, tag, adcp_use, error taxonomy - Conformance test vectors as the only deterministic path to cover every webhook_signature_* error code - Use the SDK's verifier; don't roll your own — canonicalization is the dominant interop-bug surface No normative change. Pairs with schema-description fix in adcontextprotocol#4273. Closes the SDK-skill sub-item of adcontextprotocol#4270. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Author
|
I have read the IPR Policy |
Author
|
Deferring to #4271 per @bokelley's triage comment on #4270 — #4271 covers the same call-adcp-agent surface atomically with the schema fixes, targets |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second leg of the two-PR shape proposed in #4270 (storyboard / SDK-skill on-ramp inventory). Pairs with #4273 (schema-description fix for
reporting-webhook.json+auth-scheme.json) — independent landing order, both close pieces of #4270.Why
The five protocol skills (
adcp-media-buy,adcp-creative,adcp-signals,adcp-governance,adcp-si,adcp-brand) all defer cross-cutting buyer-side basics with:That skill teaches
idempotency_key, theaccountoneOf,status:'submitted'polling, and error recovery — but was silent on webhook signing. New buyers readingpush-notification-config.jsonsee a visibleauthenticationfield and reach for it; the modern 9421 default (omit the block, verify against the seller's JWKS) is invisible from the schema alone. That's the silent-default trap I called out in #4270 inventory.This PR adds a section to the cross-cutting skill so all five protocol skills inherit the framing.
What this PR does
Single new H3 in
skills/call-adcp-agent/SKILL.mdtitled "Webhook signing — default to RFC 9421, don't reach forauthentication", placed inside "Non-obvious rules every buyer must follow" right after the async-polling section. Covers:brand.jsonagents[].jwks_uri; buyer verifies via that JWKS; no shared secret on the wire.push_notification_config.authenticationselects legacy; absence selects 9421. Buyer MUST NOT attempt try-9421-then-HMAC verification.@method,@authority,@target-uri,content-type,content-digest— all required on webhooks; no policy branch);tag=\"adcp/webhook-signing/v1\";adcp_use=\"webhook-signing\"; error taxonomywebhook_signature_*.compliance/{version}/test-vectors/webhook-signing/as the only deterministic path to cover everywebhook_signature_*error code.request-signing/README.md).Plus a changeset entry mirroring the convention from #2506.
What this PR does NOT do
security.mdx§ Webhook callbacks at the on-ramp surface where SDK consumers actually read them.adcp-media-buy,adcp-signals, etc.) — they delegate tocall-adcp-agentalready, so this single addition flows through.dist/regen;skills/is the source.Test plan
docs/building/implementation/security#verifier-checklist-for-webhooks,#webhook-error-taxonomy)Cross-references
I have read the IPR Policy