Uniform serialization seam for create_a2a/mcp_webhook_payload return shapes

[bokelley]

Problem

adcp.webhooks exports two helpers that adopters use when forwarding lifecycle events to a buyer-registered push_notification_config.url:

Helper	Returns	Serialization API
create_a2a_webhook_payload	a2a_pb2.Task / a2a_pb2.TaskStatusUpdateEvent (protobuf, since a2a-sdk 1.0+)	MessageToDict(...)
create_mcp_webhook_payload	dict[str, Any] (today; ideally McpWebhookPayload Pydantic)	already-dict, but adopters wrap as McpWebhookPayload.model_construct(**dict) to get a typed shape

A sender that accepts "any AdCP webhook payload" can't uniformly serialize the result. Adopters end up writing per-shape dispatch:

if isinstance(payload, (Task, TaskStatusUpdateEvent)):
    payload_dict = MessageToDict(payload, preserving_proto_field_name=False)
elif isinstance(payload, McpWebhookPayload):
    payload_dict = payload.model_dump(mode="json", exclude_none=True)
elif isinstance(payload, dict):
    payload_dict = payload

Brittle: a future a2a-sdk version that adds a Pydantic façade would silently change which branch runs, and every adopter has to repeat this dispatch in their HTTP send path.

Repro (downstream context)

Before this dispatch was added in salesagent PR #209, the salesagent protocol_webhook_service.send_notification called payload.model_dump(...) unconditionally. With a2a.types.Task resolving to a protobuf message in a2a-sdk 1.0+, this raised:

AttributeError: 'Task' object has no attribute 'model_dump'

…mid-delivery. Webhook silently failed; buyer never received completion notification. salesagent's investigation chain in bokelley/salesagent#64 traced the failure.

Proposal

Add a uniform serialization seam to adcp.webhooks:

from typing import Any
from a2a.types import Task, TaskStatusUpdateEvent
from adcp.types import McpWebhookPayload

def to_wire_dict(
    payload: Task | TaskStatusUpdateEvent | McpWebhookPayload | dict[str, Any],
) -> dict[str, Any]:
    """Serialize any webhook payload to a JSON-ready dict.

    - protobuf (Task / TaskStatusUpdateEvent) → MessageToDict with
      preserving_proto_field_name=False so JSON keys match the A2A wire
      spec (camelCase: ``id``, ``taskId``, ``contextId``).
    - Pydantic (McpWebhookPayload, future Pydantic façades) → model_dump.
    - dict → return as-is (legacy adopter passthrough).
    """
    from google.protobuf.json_format import MessageToDict

    if isinstance(payload, (Task, TaskStatusUpdateEvent)):
        return MessageToDict(payload, preserving_proto_field_name=False)
    if isinstance(payload, McpWebhookPayload):
        return payload.model_dump(mode="json", exclude_none=True)
    if isinstance(payload, dict):
        return payload
    raise TypeError(
        f"Unsupported webhook payload type {type(payload).__name__}: expected "
        "Task / TaskStatusUpdateEvent (protobuf), McpWebhookPayload (pydantic), or dict"
    )

Adopters then do payload_dict = to_wire_dict(payload) regardless of which builder produced it. Backward-compatible: existing per-shape dispatch keeps working; to_wire_dict is opt-in.

Bonus: align return types

create_mcp_webhook_payload returning McpWebhookPayload (Pydantic) instead of dict[str, Any] would let adopters drop the .model_construct(**dict) ceremony. salesagent's context_manager.py carries a TODO about this:

# TODO: Fix in adcp python client - create_mcp_webhook_payload should return
# McpWebhookPayload instead of dict[str, Any] for proper type safety
mcp_payload_dict = create_mcp_webhook_payload(step.step_id, status_enum, step.response_data)
payload = McpWebhookPayload.model_construct(**mcp_payload_dict)

With consistent return types and to_wire_dict as the single serialization seam, adopters never have to know the underlying shape.

Acceptance criteria

• adcp.webhooks.to_wire_dict exported from adcp.webhooks and adcp package root.
• Roundtrip test: to_wire_dict(create_a2a_webhook_payload(...)) produces a dict with id / contextId keys (camelCase per A2A wire).
• Roundtrip test: to_wire_dict(create_mcp_webhook_payload(...)) produces a dict with task_id / task_type (MCP schema).
• Optional: create_mcp_webhook_payload returns McpWebhookPayload instead of dict (with a deprecation shim for one minor release).

References

• Downstream investigation: bokelley/salesagent#64
• Downstream fix that worked around the gap: bokelley/salesagent PR #209 — see src/services/protocol_webhook_service.py:113-138
• Tracking issue with full salesagent context: bokelley/salesagent#222

Out of scope

• Buyer-controlled webhook payload shape (separate AdCP spec extension — see bokelley/salesagent#224)

[bokelley]

Triage

Classification: Feature request
Bucket(s): client
Status: deferred

What the experts said:

• Fold candidate: PR fix(webhooks): correct type annotations for extract_webhook_result_data and payload builders #600 (draft, same author, still iterating) modifies src/adcp/webhooks.py — the same file all three acceptance criteria for this issue touch. The bonus return-type change to create_mcp_webhook_payload directly overlaps fix(webhooks): correct type annotations for extract_webhook_result_data and payload builders #600's annotation work on that function's signature.
• The core ask is sound and non-breaking: _payload_to_dict (private) already implements the same Task | TaskStatusUpdateEvent | Pydantic | dict dispatch internally — to_wire_dict is just that made public and re-exported. Low implementation risk once the file is stable.

My take: Deferring until #600 merges keeps the file history readable, avoids rebase noise, and lets the return-type change land cleanly on top of #600's annotation work rather than alongside it. Commented on PR #600 to flag the fold opportunity.

Blocked-on: #600 — resurfaces on merge.

---

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

---

Generated by Claude Code