Conformance: synchronous completion must not emit a webhook by default

[bokelley]

Summary

The spec is clear that a synchronous completion fires no webhook even when push_notification_config is present. Yet both reference SDKs default to the opposite — they emit a completion webhook on the synchronous-success arm when a push URL is supplied. Two independent implementations converging on a behavior the spec forbids is a signal worth a WG decision: either the SDKs should conform, or the spec should sanction an opt-in.

What the spec says today (clear)

docs/building/by-layer/L3/webhooks.mdx ("When webhooks fire"):

"Webhooks are sent for each status change after the initial response, as long as push_notification_config is in the request. If the task completes synchronously (initial response is already completed or failed), no webhook is sent — you already have the result."

Reinforced by:

• static/schemas/source/media-buy/get-products-request.json & static/schemas/source/signals/get-signals-request.json — push is "meaningful only for brief/refine requests that enter the async lifecycle"; the MUST-deliver obligation is conditioned on "...AND the seller returns a Submitted envelope."
• docs/building/by-layer/L3/async-operations.mdx, static/schemas/source/enums/task-status.json (submitted description), and the L0 MCP/A2A guides ("initial response is already terminal → no webhook is sent").

The rationale is explicit: on a synchronous completion the buyer already has the result inline, so a webhook would just duplicate the payload.

What both reference SDKs actually do (the divergence)

Both default to emitting a completion webhook on the synchronous arm when push_notification_config.url is present:

• JS @adcp/sdk — autoEmitCompletionWebhooks defaults to true (src/lib/server/decisioning/runtime/from-platform.ts). Its doc-comment justifies this on buyer-convenience grounds ("buyers passing the URL expect notification regardless of whether the seller routed the call sync vs HITL; v5 adopters routinely wired this manually") and synthesizes a task_id since sync responses allocate no registry task.
• Python adcp-client-python — auto_emit_completion_webhooks defaults to true in production serve(); handler._maybe_auto_emit_sync_completion fires the sync-completion webhook and its docstring states it "mirrors the JS-side routeIfHandoff logic."

Neither cites a spec clause — both are deliberate product choices that exceed the spec.

Why the SDK behavior is reasonable

A buyer that supplies push_notification_config is frequently fire-and-forget: send the request, expect a callback, don't necessarily branch on the synchronous HTTP body. "I gave you a URL, call me when it's done" is a clean, uniform mental model that frees the buyer from handling sync-vs-async differently. The fact that two independent implementations (and, per the JS note, many v5 adopters by hand) converged on it suggests real demand.

Why the spec currently forbids it

Avoids duplicating the inline result onto the webhook ("you already have the result"), and keeps the webhook channel semantically bound to the async (submitted) lifecycle.

Options for the WG

• A. Keep the spec; SDKs conform. Sellers/SDKs MUST NOT emit a webhook on synchronous completion. SDK convenience emitters become explicit, off-by-default opt-ins documented as non-spec. (Requires both SDKs to flip their defaults.)
• B. Spec sanctions an opt-in. Define a mechanism — e.g. a buyer-signalable flag, or "a seller MAY also deliver a terminal notification on synchronous completion when push_notification_config is present" — with operation_id correlation and explicit acknowledgement that this duplicates the inline result.
• C. Spec requires it. push_notification_config present ⇒ the buyer is always notified via webhook, sync or async ("passed a URL ⇒ always called"). Strongest buyer guarantee; aligns the spec to current SDK defaults; cost is the duplicated payload.

Recommendation

Discuss B vs C. The convergence of both reference SDKs (and hand-rolled v5 adopters) on emitting points to a genuine buyer expectation that the spec doesn't currently meet. At minimum, the spec and the reference SDKs should not silently disagree — today a conformance test would mark both SDKs non-conformant by default.

Edge cases to settle if sanctioned (B/C)

• operation_id correlation on a sync-completion webhook (buyer-supplied, echoed verbatim).
• Double-delivery semantics: the buyer receives the result both inline and via webhook — is that explicitly fine, idempotent, de-dupable?
• Interaction with idempotency replay (does a replayed sync response re-fire the webhook?).
• Keep the existing prohibition intact: push_notification_config presence MUST NOT force a guaranteed-sync op (buying_mode/discovery_mode: "wholesale") onto the async/Submitted arm — a sync-completion webhook is a distinct thing from routing async and should be scoped accordingly.

References

• docs/building/by-layer/L3/webhooks.mdx (≈154–169)
• static/schemas/source/media-buy/get-products-request.json, static/schemas/source/signals/get-signals-request.json (push_notification_config descriptions)
• docs/building/by-layer/L3/async-operations.mdx; static/schemas/source/enums/task-status.json; static/schemas/source/core/push-notification-config.json
• JS: adcontextprotocol/adcp-client src/lib/server/decisioning/runtime/from-platform.ts (autoEmitCompletionWebhooks, default true)
• Python: adcontextprotocol/adcp-client-python src/adcp/decisioning/handler.py (_maybe_auto_emit_sync_completion) + serve() default auto_emit_completion_webhooks=True

Surfaced while implementing async discovery parity (get_products/get_signals) in the Python SDK; the sync-vs-async webhook question generalizes to every task-capable operation.

[bokelley]

Triage

Classification: RFC / Spec question
Bucket(s): spec / protocol, compliance-suite, schema
Status: ready-for-human
Milestone: Spec Backlog

What the experts said:

• ad-tech-protocol-expert: B sound-with-caveats, C unsound — C redefines push_notification_config semantics from "lifecycle notification" to "delivery guarantee," needs a major bump, and the current task_id: required in mcp-webhook-payload.json makes any synthesized ID a schema violation (no registry entry for sync completions). A is spec-correct but a de-facto breaking change for v5 adopters who wired on the SDK default. Three open blockers for any B-variant: task_id disposition on sync fires, idempotency-replay re-fire semantics, and conformance storyboard step kind.
• adtech-product-expert: Fire-and-forget buyer demand is real, but a receiver that never reads the sync HTTP body is a buyer-side bug, not a spec gap. Bare MAY creates durable seller-side ambiguity (some sellers emit, some don't, buyers can't know which). Recommends A + explicit sync_completion_notify opt-in field in push_notification_config rather than any blanket permission — keeps sellers predictable, puts the buyer in control.
• ad-tech-protocol-expert-deep: C breaks A2A lineage (AdCP ties its lifecycle to A2A TaskState; A2A tasks always have registry IDs) and OpenRTB convention (nurl/burl don't duplicate synchronous results). Closes on a two-track recommendation: Track 1 is patch-eligible now and doesn't require a WG vote; Track 2 is the 3.1 WG decision.

My take: All three experts agree C is off the table and Track 1 is patch-eligible on 3.0.x without waiting on the WG decision. The remaining question is whether buyer demand warrants a 3.1 protocol change and, if so, which form. @bokelley, two decisions below.

---

Track 1 — patch-eligible now, no WG vote needed:

// @adcp/sdk from-platform.ts
- autoEmitCompletionWebhooks: true   // non-conformant; v5 adopters relied on this
+ autoEmitCompletionWebhooks: false  // spec-conformant; SDK opt-in stays available

// adcp-client-python serve()
- auto_emit_completion_webhooks=True
+ auto_emit_completion_webhooks=False

Plus a conformance storyboard phase: request → synchronous completed response → assert no webhook fires. Patch-eligible on 3.0.x. Closes the current conformance gap regardless of Track 2.

---

Track 2 — buyer-signal opt-in (WG vote, 3.1 track):

// push-notification-config.json — new optional field
+ "sync_completion_notify": {
+   "type": "boolean",
+   "default": false,
+   "description": "Opt-in: seller delivers a terminal webhook even on sync
+     completion when push_notification_config is present. The inline HTTP
+     result remains authoritative (cf. wholesale-feed-webhook 'not binding
+     authority' framing). Sellers MUST honor only when advertised in
+     get_adcp_capabilities. task_id absent; operation_id required."
+ }

Five pre-conditions before shipping: (1) task_id optional in mcp-webhook-payload.json for sync-completion events, with a sync_completion: true discriminator; (2) capability advertisement in get_adcp_capabilities; (3) normative idempotency_key synthesis rule (keyed on operation_id + task_type + status + timestamp_s); (4) "inline result is authoritative" normative text in webhooks.mdx; (5) conformance storyboard update for the opt-in arm. Minor bump on main (3.1 track) — not backportable to 3.0.x.

Alternative (bare MAY, potentially patch-eligible as a normative clarification): "A seller MAY also deliver a terminal notification on synchronous completion when push_notification_config is present." Simpler, but leaves seller behavior ambiguous — buyers cannot signal intent and cannot probe capability — which is the failure mode the product expert flagged.

---

@bokelley, your call:

1. Track 1: Approve SDK-default flip + conformance storyboard negative test as a 3.0.x patch. This closes the conformance gap now.
2. Track 2: Is fire-and-forget buyer demand confirmed enough to warrant the 3.1 investment? If yes: buyer-signal field (requires the five pre-conditions above) or bare-MAY language (simpler but ambiguous seller behavior)?

---

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

---

Generated by Claude Code