feat: allow adopter-owned webhook_signing capability without SDK WebhookSender

[bokelley]

Summary

After integrating adcp==6.2.0b4, Prebid Sales Agent no longer needs the older capabilities-status or publisher-portfolio monkey patches: capabilities_response() emits status: "completed" natively, and DecisioningPlatform.get_adcp_capabilities_for_request() lets the seller return tenant-scoped media_buy.portfolio.publisher_domains.

One local SDK workaround remains: Sales Agent still monkey-patches PlatformHandler.get_adcp_capabilities() to append tenant-specific webhook_signing because the typed request-scoped capabilities path validates webhook_signing.supported=True against an SDK-wired WebhookSender.

Sales Agent signs and sends buyer-protocol webhooks through its own service path, backed by tenant-specific signing credentials. It can honestly advertise RFC 9421 webhook signing for tenants with an active usable credential, but it cannot currently express that through the SDK typed capabilities hook without also wiring the SDK webhook sender/supervisor stack.

Current adopter-side workaround

Sales Agent imports a side-effect module that replaces:

adcp.decisioning.handler.PlatformHandler.get_adcp_capabilities

The patch calls the original SDK handler and, when missing, appends:

{
  "webhook_signing": {
    "supported": true,
    "profile": "adcp/webhook-signing/v1",
    "algorithms": ["ed25519"],
    "legacy_hmac_fallback": true
  }
}

The values are resolved per tenant from Sales Agent's own TenantSigningCredential store. When no usable credential exists, Sales Agent advertises:

{
  "webhook_signing": {
    "supported": false,
    "legacy_hmac_fallback": true
  }
}

Expected

The SDK should provide a first-class way for adopters that own webhook delivery/signing outside the SDK WebhookSender implementation to advertise dynamic webhook_signing capabilities without monkey-patching PlatformHandler.

Possible approaches:

• Allow DecisioningPlatform.get_adcp_capabilities_for_request() to return webhook_signing when the adopter declares an explicit “external webhook sender/signing is handled by platform” capability/flag.
• Or expose a narrower hook just for webhook_signing capability resolution, with ToolContext/tenant context available.
• Or make validate_webhook_signing_for_capabilities() accept an adopter-provided validator/interface rather than requiring the SDK WebhookSender instance.

The important property is that seller apps should compose with SDK capabilities projection and validation, not patch PlatformHandler.get_adcp_capabilities() after the fact.

Why this matters

Webhook signing is tenant-specific in multi-tenant sellers, and some adopters already have production webhook delivery/signing infrastructure outside the SDK. Requiring SDK-owned WebhookSender wiring to advertise webhook_signing forces otherwise clean adopters into local response patches.

Related: #867, which is now mostly resolved in beta 4 for status + dynamic portfolio, but does not cover this remaining webhook-signing validation/extension point.

[bokelley]

Triage

Classification: Feature request
Bucket(s): handlers (no handlers label in this repo — noted in run summary)
Status: ready-to-implement

What the experts said:

• code-reviewer: Guard must live inside validate_webhook_signing_for_capabilities (not in the callers) so both serve.py:412 and handler.py:1624 auto-inherit the bypass; new field belongs in the SDK-internal block after auto_paginate; non-breaking.
• ad-tech-protocol-expert: Spec-compliant — RFC 9421 and the WebhookSigning schema are outcome-focused; governance_aware is the right design precedent; the alternative (widen supervisor escape hatch to warn-not-raise) is less safe as it silently bypasses for all un-wired adopters, not just opt-in ones.
• security-reviewer: No blockers; add logger.warning at the skip point (mirrors webhook_emit.py:452–461); document that external signing credentials must not flow through RequestContext.metadata — the suffix-fence catches common key patterns but bespoke names (e.g. tenant_jwk) would pass through.

My take: All three experts converge on an explicit bool opt-in on DecisioningCapabilities. Because the guard lives inside the validator, both call sites are covered without touching callers. PR authorization gate does not pass (no /triage execute, no auto-pr-ok label), so this is ready-to-implement.

Implementation scope:

• src/adcp/decisioning/platform.py — Add external_webhook_signing: bool = False after auto_paginate in the SDK-internal field block. Docstring: mirrors governance_aware precedent (platform.py:133–147); adopter owns RFC 9421 compliance; credentials for external signing must not flow through RequestContext.metadata (point to dispatch._CREDENTIAL_SHAPED_KEY_SUFFIXES).
• src/adcp/decisioning/webhook_emit.py — In validate_webhook_signing_for_capabilities, after the supported guard: if getattr(capabilities, "external_webhook_signing", False): logger.warning("[adcp.decisioning] capabilities.webhook_signing.supported=True with external_webhook_signing=True — RFC 9421 compliance is the adopter's responsibility; SDK cannot verify external sender."); return. Update the function docstring to document this path.
• No changes needed to callers — serve.py:412 and handler.py:1624 both call the validator directly; the guard inside the validator covers both automatically.
• Required tests: (a) external_webhook_signing=True + webhook_signing.supported=True + no SDK sender → passes validation + WARNING fires; (b) default (external_webhook_signing=False) + webhook_signing.supported=True + no sender → still raises (existing behavior preserved); (c) external_webhook_signing=True + webhook_signing.supported=False → no-op.

---

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

---

Generated by Claude Code