fix(decisioning): disable sync task webhooks by default (#1020)

Author: bokelley

MIGRATION_v6_to_v7.md

@@ -44,3 +44,23 @@ AdCP 3.0 is upgraded on reads and downgraded on writes. AdCP 3.1 requires the
 `media_buy.features.canonical_creatives` capability or unambiguous
 request-local evidence. AdCP 3.2 will be canonical by contract once supported;
 advertising `canonical_creatives: false` there will be an error.
+
+## Synchronous completion webhooks
+
+`auto_emit_completion_webhooks` now defaults to `False`. AdCP forbids a task
+webhook when the initial response is already terminal: the result is available
+inline and no registry task exists for a webhook `task_id`.
+
+If an existing buyer depends on receiving both copies, temporarily pass
+`auto_emit_completion_webhooks=True` to `serve()` or
+`create_adcp_server_from_platform()`. This retains the former behavior as a
+non-conformant compatibility extension with a synthetic, unpollable `sync-*`
+task ID. Update the buyer to consume the inline result, then remove the opt-in.
+
+This setting only controls synthetic synchronous-completion delivery. Terminal
+webhooks for real `TaskHandoff` requests remain enabled when the request supplies
+`push_notification_config` and a webhook sender or supervisor is configured. The
+framework rejects a push-configured handoff before task creation when no transport
+is available, rather than returning `submitted` and silently dropping the callback.
+Adopters that deliver terminal task webhooks themselves can set the independent
+`auto_emit_task_webhooks=False` ownership flag.

docs/handler-authoring.md

@@ -1277,16 +1277,28 @@ MCP for production agents.
 
 ## Webhooks
 
-When `auto_emit_completion_webhooks=True` (the default), the framework fires a
-sync-completion webhook after every successfully-dispatched tool call whose task
-type is in the spec's webhook-eligible set (`create_media_buy`, `activate_signal`,
-and their siblings). Buyers who register `push_notification_config.url` receive
-these notifications automatically.
-
-The framework requires a sender or supervisor at boot — it raises `AdcpError`
-rather than silently dropping notifications if neither is wired and auto-emit is on.
-Set `auto_emit_completion_webhooks=False` only if you emit webhooks manually inside
-your platform methods.
+Synchronous terminal responses do not emit task webhooks. This is the default:
+`auto_emit_completion_webhooks=False`. The buyer already has the result inline,
+and no registry task exists for a webhook `task_id`.
+
+`TaskHandoff` is different. When the initial response is `submitted` and the
+request includes `push_notification_config`, the framework delivers the required
+terminal completion or failure webhook through the configured sender or supervisor.
+The sync-completion compatibility flag does not disable that async delivery. A
+push-configured handoff is rejected before task creation when no delivery transport
+is configured, so the server cannot return `submitted` and then silently drop the
+required callback.
+
+`auto_emit_task_webhooks=True` controls framework ownership of these real task
+notifications. Set it to `False` only when adopter code owns terminal webhook
+delivery itself. This is separate from `auto_emit_completion_webhooks`, which only
+controls the legacy synthetic sync behavior.
+
+Existing integrations that relied on duplicate inline and webhook delivery can
+temporarily set `auto_emit_completion_webhooks=True`. This is a non-conformant
+compatibility extension: it synthesizes an unpollable `sync-*` task ID. The
+framework requires a sender or supervisor at boot when this mode is enabled.
+Migrate buyers to consume the inline terminal response, then remove the opt-in.
 
 ### Sender constructors
 

examples/README.md

@@ -83,7 +83,7 @@ Related skills: `build-seller-agent`, `build-generative-seller-agent`,
 
 ## Webhooks
 
-- [`hello_seller_with_webhooks.py`](hello_seller_with_webhooks.py) — wire an `InMemoryWebhookDeliverySupervisor` so completion webhooks reach buyers who register `push_notification_config.url`; uses `WebhookSender.from_bearer_token`.
+- [`hello_seller_with_webhooks.py`](hello_seller_with_webhooks.py) — legacy, non-conformant sync-completion compatibility example using `InMemoryWebhookDeliverySupervisor`; normal `TaskHandoff` notifications require no sync opt-in.
 
 See `docs/handler-authoring.md#webhooks` for the full `WebhookSender`
 constructor comparison (bearer vs RFC 9421 JWK signing).

examples/hello_seller.py

@@ -373,10 +373,8 @@ def _get_packages(req: Any) -> list[dict[str, Any]]:
     # server. Default port 3001 over streamable-http; override via
     # ``serve(seller, port=...)``.
     #
-    # ``auto_emit_completion_webhooks=False`` opts out here because this
-    # example has no signing key.  Production sellers want webhooks on so
-    # buyers who register ``push_notification_config.url`` get sync-
-    # completion notifications.  Pick a constructor and pass
+    # Synchronous terminal responses do not emit task webhooks. For real
+    # TaskHandoff completion notifications, pick a constructor and pass
     # ``webhook_supervisor=`` (retry + circuit breaker, recommended) or
     # ``webhook_sender=`` (transport only):
     #
@@ -399,4 +397,4 @@ def _get_packages(req: Any) -> list[dict[str, Any]]:
     #   serve(HelloSeller(), name="hello-seller", webhook_supervisor=supervisor)
     #
     # See docs/handler-authoring.md#webhooks for the full wiring recipe.
-    serve(HelloSeller(), name="hello-seller", auto_emit_completion_webhooks=False)
+    serve(HelloSeller(), name="hello-seller")

examples/hello_seller_async_handoff.py

@@ -288,9 +288,9 @@ def _echo_packages(req: Any) -> list[dict[str, Any]]:
     serve(
         HelloSellerHybrid(),
         name="hello-seller-hybrid",
-        # Opt out of F12 auto-emit so the example boots without a
-        # ``webhook_sender``. Production sellers wire ``webhook_sender=``
-        # so buyers who register ``push_notification_config.url`` get
-        # completion notifications when their TaskHandoff finishes.
+        # Pin the conformant sync-completion default explicitly.
+        # Production sellers wire ``webhook_sender=`` so buyers who
+        # register ``push_notification_config.url`` get completion
+        # notifications when their TaskHandoff finishes.
         auto_emit_completion_webhooks=False,
     )

examples/hello_seller_audience.py

@@ -64,9 +64,8 @@ def sync_audiences(
 def main() -> None:
     """Boot the seller on http://localhost:3001/mcp.
 
-    ``auto_emit_completion_webhooks=False`` opts out so this example
-    boots without a ``webhook_sender``. In production, wire
-    ``webhook_sender=`` for buyer notification.
+    Synchronous terminal responses remain inline-only by default. Wire
+    ``webhook_sender=`` when adding ``TaskHandoff`` support.
     """
     serve(HelloAudienceSeller(), auto_emit_completion_webhooks=False)
 

examples/hello_seller_brand_rights.py

@@ -87,9 +87,8 @@ def acquire_rights(
 def main() -> None:
     """Boot the seller on http://localhost:3001/mcp.
 
-    ``auto_emit_completion_webhooks=False`` opts out so this example
-    boots without a ``webhook_sender``. In production, wire
-    ``webhook_sender=`` for buyer notification.
+    Synchronous terminal responses remain inline-only by default. Wire
+    ``webhook_sender=`` when adding ``TaskHandoff`` support.
     """
     serve(HelloBrandRightsSeller(), auto_emit_completion_webhooks=False)
 

examples/hello_seller_catalog.py

@@ -93,9 +93,8 @@ def sync_catalogs(self, req: Any, ctx: RequestContext[Any]) -> list[dict[str, An
 def main() -> None:
     """Boot the seller on http://localhost:3001/mcp.
 
-    ``auto_emit_completion_webhooks=False`` opts out so this example
-    boots without a ``webhook_sender``. In production, wire
-    ``webhook_sender=`` for buyer notification.
+    Synchronous terminal responses remain inline-only by default. Wire
+    ``webhook_sender=`` when adding ``TaskHandoff`` support.
     """
     serve(HelloCatalogSeller(), auto_emit_completion_webhooks=False)
 

examples/hello_seller_creative.py

@@ -102,16 +102,15 @@ def main() -> None:
       governance tools (per-specialism filter).
     * ``tools/call build_creative`` returns the synthesized manifest.
 
-    The ``auto_emit_completion_webhooks=False`` opt-out keeps this
-    example minimal. In production, wire ``webhook_sender=`` so
-    buyers who register ``push_notification_config.url`` get
-    completion notifications:
+    Synchronous terminal responses remain inline-only. If this seller
+    returns a ``TaskHandoff``, wire ``webhook_sender=`` so buyers who
+    register ``push_notification_config.url`` get terminal notifications:
 
         from adcp.webhook_sender import WebhookSender
         sender = WebhookSender.from_jwk(...)
         serve(HelloCreativeSeller(), webhook_sender=sender)
     """
-    serve(HelloCreativeSeller(), auto_emit_completion_webhooks=False)
+    serve(HelloCreativeSeller())
 
 
 if __name__ == "__main__":

examples/hello_seller_signals.py

@@ -137,14 +137,13 @@ async def _async_activation(self, task_ctx: Any) -> dict[str, Any]:
 def main() -> None:
     """Boot the seller on http://localhost:3001/mcp.
 
-    ``auto_emit_completion_webhooks=False`` opts out of the sync
-    completion-webhook auto-emit so this example boots without a
-    ``webhook_sender``. In production, wire ``webhook_sender=`` so
+    Synchronous terminal responses remain inline-only by default. In
+    production, wire ``webhook_sender=`` so
     buyers who register ``push_notification_config.url`` on
     ``activate_signal`` get notifications when a TaskHandoff
     completes.
     """
-    serve(HelloSignalsSeller(), auto_emit_completion_webhooks=False)
+    serve(HelloSignalsSeller())
 
 
 if __name__ == "__main__":