Skip to content

feat(webhooks): stable 3.1 catalog notification exports and sender helper #832

Closed

Description

@bokelley

Context

Python SDK 5.7.0 includes generated Pydantic models for accounts[].notification_configs[], NotificationConfig, and the 3.1 wholesale feed webhook schema under generated/internal paths. It also has WebhookSender.send_raw(...), which can send any pre-shaped payload safely.

For seller implementations wiring AdCP 3.1 catalog notifications, the remaining work is easy to get subtly wrong:

  • importing internal adcp.types.generated_poc.* modules instead of stable SDK aliases
  • hand-building WholesaleFeedWebhook / WholesaleFeedEvent dicts
  • preserving account-anchored subscriber_id / account_id semantics
  • preserving event_types filters
  • preserving declarative replace semantics for accounts[].notification_configs[]
  • emitting product/signal notifications through the signed sender with byte-exact body/signature behavior

Problem

There is no stable top-level SDK surface for these catalog webhook building blocks. In 5.7.0:

import adcp
from adcp import types

hasattr(adcp, "NotificationConfig")       # False
hasattr(types, "NotificationConfig")      # False
hasattr(adcp, "WholesaleFeedWebhook")     # False
hasattr(types, "WholesaleFeedWebhook")    # False
hasattr(adcp, "WholesaleFeedEvent")       # False
hasattr(types, "WholesaleFeedEvent")      # False

WebhookSender exposes send_mcp, send_collection_list_changed, send_property_list_changed, etc., but not a dedicated send_wholesale_feed(...) helper. Downstream sellers can use send_raw, but that leaves envelope construction and protocol invariants to each implementation.

Proposal

Add stable SDK exports and a helper for AdCP 3.1 catalog notifications:

  • export NotificationConfig from adcp and adcp.types
  • export WholesaleFeedWebhook and WholesaleFeedEvent from stable adcp / adcp.types paths
  • add a builder or sender helper, e.g.:
await sender.send_wholesale_feed(
    url=subscription.url,
    subscriber_id=subscription.subscriber_id,
    account_id=account_id,
    notification_type="signal.updated",
    wholesale_feed_version=feed_version,
    cache_scope="public",
    event=event,
)

Optionally also provide small event builders for product.created/updated/priced/removed and signal.created/updated/priced/removed.

Acceptance criteria

  • Stable imports for NotificationConfig, WholesaleFeedWebhook, and WholesaleFeedEvent without using generated_poc modules.
  • Helper validates required account/subscriber fields and event type/entity consistency.
  • Helper sends through WebhookSender so RFC9421/HMAC/Bearer behavior and SSRF protections remain centralized.
  • Tests cover product and signal events, including subscriber_id, account_id, wholesale_feed_version, cache_scope, and event_types filtering guidance.
  • Docs include seller-side guidance for applying accounts[].notification_configs[] from sync_accounts and firing catalog webhooks.

Downstream impact

This would prevent every Python seller implementation from hand-rolling wholesale feed webhook envelopes and reduce drift with the JS SDK catalog-sync receiver behavior.

Activity

  1. added
    no-triageSkip the Claude triage bot — human or designated agent will handle this issue
    on May 23, 2026
  2. bokelley commented on May 23, 2026

    @bokelley
    ContributorAuthor

    Closing as completed by merged #833. That PR added stable NotificationConfig / WholesaleFeedWebhook / WholesaleFeedEvent exports plus WebhookSender wholesale-feed sending helpers, docs, and tests.

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-triagedno-triageSkip the Claude triage bot — human or designated agent will handle this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions