Skip to content

4.0: drop required: ["authentication"] from reporting-webhook and artifact_webhook #4288

Closed as not planned

Description

@bokelley

Context

In AdCP 3.x, authentication is required on:

  • static/schemas/source/core/reporting-webhook.json
  • artifact_webhook block of static/schemas/source/media-buy/create-media-buy-request.json

This forces every receiver into the deprecated Bearer / HMAC-SHA256 path even though the canonical signing profile is RFC 9421 (seller signs with the key published at its brand.json agents[].jwks_uri; buyer verifies against the seller's JWKS).

The schema descriptions already advertise this: "This field is required in AdCP 3.x; the requirement is removed in AdCP 4.0 when the default RFC 9421 path becomes the only path" (landed in #4271).

Scope for 4.0

  1. Drop "authentication" from required[] in reporting-webhook.json.
  2. Drop "authentication" from the artifact_webhook.required[] block in create-media-buy-request.json.
  3. Confirm the security doc's webhook-callbacks section covers signing-mode selection for both surfaces (it currently focuses on push_notification_config); extend if not.
  4. Decide whether to remove the authentication block entirely or keep it as an optional opt-in for legacy receivers. Recommendation: keep optional in 4.0 with a 4.x removal target — gives sellers a one-major escape hatch.

Why this isn't 3.x

Per playbook, removing a required[] constraint is a signing-profile change and never patch-eligible. Description-only updates landed in #4271 (patch, 3.0.x). This issue tracks the structural change for the next major.

Refs

Activity

  1. added this to the 4.0 milestone on May 9, 2026
  2. added
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 9, 2026
  3. bokelley commented on May 9, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request — 4.0 structural schema change
    Bucket(s): spec / protocol, security-sensitive
    Status: ready-for-human
    Milestone: 4.0 (#5)

    What the experts said:

    • ad-tech-protocol-expert: Option A preferred per OpenRTB/VAST precedent (optional + sunset anchor); blocker — reporting-webhook.json and artifact_webhook lack the mode-switch precedence language already in push-notification-config.json ("presence of this block selects the legacy scheme; absence selects 9421; seller MUST NOT sign both ways"). Also flags scope gap: sync-governance-request.json has required: ["url", "authentication"] on the governance-agent webhook surface and isn't included.
    • security-reviewer: Recommends Option B (remove entirely) — prose-reliant switch ambiguity is a downgrade/MITM surface; additional gaps in artifact-webhook-payload.json (idempotency_key anchors to HMAC secret, not RFC 9421 keyid) and per_principal_key_isolation enforcement for multi-tenant sellers on artifact_webhook. Credential-zeroing guidance is also missing from the migration path.

    My take: Experts split on A vs. B — protocol precedent points to A, security hygiene points to B. Both agree the required[] drop alone is insufficient: the two schemas need description upgrades before this is shippable, and sync-governance-request.json is an unaddressed sibling surface.

    @bokelley, your call: Option A (keep optional, explicit sunset commitment) or Option B (remove in 4.0, clean break)?

    Option A — Drop from required[], keep optional (one-major escape hatch):

    // reporting-webhook.json required[]
    - "required": ["url", "authentication", "reporting_frequency"]
    + "required": ["url", "reporting_frequency"]
    // authentication stays optional; presence selects legacy mode per push-notification-config.json pattern
    // + copy mode-switch precedence language into authentication description
    // + sunset language: "Removed in AdCP 5.0"

    Option B — Remove authentication entirely (clean break):

    // reporting-webhook.json
    - "authentication": { "type": "object", ... },
    - "required": ["url", "authentication", "reporting_frequency"]
    + "required": ["url", "reporting_frequency"]
    // RFC 9421 is the only path; no escape hatch

    Either option should also address: sync-governance-request.json authentication surface, artifact-webhook-payload.json idempotency_key anchor, and the migration guide credential-zeroing requirement.


    Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}


    Generated by Claude Code

  4. added
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 9, 2026
  5. bokelley commented on Oct 13, 2026

    @bokelley
    ContributorAuthor

    Filed #8176 to relax this in 3.3 rather than wait for 4.0: authentication becomes optional on reporting_webhook and artifact_webhook only for requests pinned to 3.3+ to a seller that declares webhook_signing.supported: true, with the same presence/absence switch as push_notification_config. That is a minor-release change (same pattern as the impressions loosening in #8089), so it does not conflict with the "not patch-eligible" reasoning here. This issue would still own the 4.0 decision to remove the block or keep it optional.

  6. bokelley commented on Nov 8, 2026

    @bokelley
    ContributorAuthor

    Superseded. #8177 (merged 2026-10-20) made authentication optional on reporting and artifact webhooks in 3.3, and full removal of webhook authentication is tracked for 4.0 in #8662.

    🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions