Repository navigation
Description
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 = payloadBrittle: 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_dictexported fromadcp.webhooksandadcppackage root. - Roundtrip test:
to_wire_dict(create_a2a_webhook_payload(...))produces a dict withid/contextIdkeys (camelCase per A2A wire). - Roundtrip test:
to_wire_dict(create_mcp_webhook_payload(...))produces a dict withtask_id/task_type(MCP schema). - Optional:
create_mcp_webhook_payloadreturnsMcpWebhookPayloadinstead 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)
Activity
bokelley commentedon May 8, 2026
Triage
Classification: Feature request
Bucket(s): client
Status: deferred
What the experts said:
src/adcp/webhooks.py— the same file all three acceptance criteria for this issue touch. The bonus return-type change tocreate_mcp_webhook_payloaddirectly overlaps fix(webhooks): correct type annotations for extract_webhook_result_data and payload builders #600's annotation work on that function's signature._payload_to_dict(private) already implements the sameTask | TaskStatusUpdateEvent | Pydantic | dictdispatch internally —to_wire_dictis 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
feat(webhooks): public to_wire_dict() serialization seam (#602)