Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/relationship-scoped-advisories.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": minor
---

Add a joined 3.2 warnings and advisories contract. Successful `create_media_buy` and `update_media_buy` responses may carry structured non-blocking warnings; continuing conditions appear as compact current advisories on media buys, packages, or package–creative assignments. Seven standard advisory types cover creative, audience, inventory, pacing, and budget risks or optimization opportunities that warrant buyer attention. Mixed publisher approvals use scoped outcomes. Every advisory-capable seller supports signed `advisories.changed` invalidations and complete `get_media_buys` repair. Assignment notifications remain independent: sellers without an advisory catalog may emit `creative.assignment_changed`, while creative-library sellers may independently expose bounded reverse assignment state through `list_creatives`. No advisory IDs, sub-versions, history API, automatic action dispatcher, or separate `get_advisories` task is introduced.
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,7 @@
"docs/media-buy/product-discovery/refinement",
"docs/media-buy/media-buys/index",
"docs/media-buy/media-buys/lifecycle",
"docs/media-buy/media-buys/advisories",
"docs/media-buy/media-buys/optimization-reporting",
"docs/media-buy/media-buys/policy-compliance",
"docs/media-buy/creatives/index",
Expand Down
6 changes: 4 additions & 2 deletions docs/accounts/tasks/sync_accounts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,9 @@ Schema enforces the exclusivity via `oneOf` — sending both shapes on the same

## Account-level webhook subscriptions

`notification_configs[]` carries account-level webhook subscribers for notifications whose lifecycle outlives any single media buy — `creative.status_changed`, `creative.purged`, `account.status_changed`, wholesale feed change webhooks (`product.*`, `signal.*`, `wholesale_feed.bulk_change`), and future account-anchored resource events after those event types are added to `notification-type.json`.
`notification_configs[]` carries account-level webhook subscribers for creative lifecycle and assignment changes, `advisories.changed`, account status, wholesale feed changes, and future account-anchored events.

Advisory and assignment subscriptions are prospective: activation or reactivation does not replay conditions that were already current. After activation, buyers establish a complete baseline through [`get_media_buys`](/docs/media-buy/task-reference/get_media_buys) before relying on later invalidations: enumerate known media-buy IDs or request every media-buy status and follow pagination to exhaustion, without an advisory filter. The optional bounded [`list_creatives`](/docs/creative/task-reference/list_creatives) projection is not sufficient to prove complete state.

`account.status_changed` is the durable account lifecycle event. Use it for status transitions after the initial `sync_accounts` result, such as `pending_approval → active`, `pending_approval → rejected`, `active → payment_required`, `active → suspended`, recovery back to `active`, or terminal `closed`. It is not a replacement for the one-shot `push_notification_config` on this task: that channel can report the async result of the original provisioning operation, while `notification_configs[]` subscribers outlive the task.

Expand All @@ -198,7 +200,7 @@ Each entry has:

- `subscriber_id` — buyer-supplied identifier, unique within the account; echoed on every fire so multi-subscriber accounts can route by endpoint
- `url` — HTTPS endpoint URL. Sellers MUST complete an endpoint activation challenge or equivalent proof-of-control before treating a new or changed active subscriber as active.
- `event_types[]` — types the subscriber wants. Only account-anchored types are permitted (today: `creative.status_changed`, `creative.purged`, `account.status_changed`, `product.created`, `product.updated`, `product.priced`, `product.removed`, `signal.created`, `signal.updated`, `signal.priced`, `signal.removed`, `wholesale_feed.bulk_change`). Sellers MUST reject any media-buy-anchored type (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment`) or agent-anchored type (`capabilities.changed`) as a per-account validation failure with [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) or [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) in `accounts[].errors[]`, and `error.field` MUST point at the invalid `event_types` entry.
- `event_types[]` — types the subscriber wants. Only account-anchored types are permitted (today: `creative.status_changed`, `creative.assignment_changed`, `advisories.changed`, `creative.purged`, `account.status_changed`, `product.created`, `product.updated`, `product.priced`, `product.removed`, `signal.created`, `signal.updated`, `signal.priced`, `signal.removed`, `wholesale_feed.bulk_change`). Sellers MUST reject any media-buy-anchored type (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment`) or agent-anchored type (`capabilities.changed`) as a per-account validation failure with [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) or [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) in `accounts[].errors[]`, and `error.field` MUST point at the invalid `event_types` entry.
- `authentication` (optional) — legacy Bearer or HMAC-SHA256. Omit to use the default RFC 9421 webhook profile. When present, the same signed-registration downgrade-resistance rules as `push_notification_config.authentication` apply. Credentials are write-only — sellers omit them on reads.
- `active` (default `true`) — set `false` to pause a subscriber without removing the registration. Sellers MAY skip only the outbound proof challenge while `active: false`; they MUST still enforce HTTPS parsing, hostname normalization, and reserved-range rejection on write. Paused subscribers MUST NOT receive fires until reactivated. Reactivation MUST repeat full SSRF validation with connect pinning plus proof-of-control for any tuple without current valid proof.

Expand Down
2 changes: 1 addition & 1 deletion docs/building/by-layer/L3/webhooks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ Webhook envelope shape is determined by **which registration mechanism the buyer
|---|---|
| AdCP `push_notification_config` (task argument, MCP/A2A/REST) | [`mcp-webhook-payload.json`](#mcp) |
| A2A `TaskPushNotificationConfig` ([`CreateTaskPushNotificationConfig`](https://a2a-protocol.org/latest/specification/) RPC, or inline `task_push_notification_config` on `SendMessage`) | A2A native `Task` / `TaskStatusUpdateEvent` per A2A 1.0 §4.3.3 |
| Account-level `sync_accounts.accounts[].notification_configs[]` | Event-specific AdCP payload schemas such as `creative-status-changed-webhook.json`, `account-status-changed-webhook.json`, or `wholesale-feed-webhook.json` |
| Account-level `sync_accounts.accounts[].notification_configs[]` | Event-specific payloads such as `creative-status-changed-webhook.json`, `creative-assignment-changed-webhook.json`, `advisories-changed-webhook.json`, `account-status-changed-webhook.json`, or `wholesale-feed-webhook.json` |
| Agent-level `sync_agent_notification_configs.notification_configs[]` | Event-specific AdCP payload schemas such as `capabilities-changed-webhook.json` |

The two channels are independent. A buyer MAY register both for the same task and receive both webhooks per status change.
Expand Down
4 changes: 4 additions & 0 deletions docs/creative/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,10 @@ Browse and filter creative assets in a creative library. Implemented by any agen
- Agents SHOULD support filtering by `concept_ids` and canonical `format_kinds` when the platform organizes creatives into concepts
- Agents MAY include dynamic content variable definitions when `include_variables=true`
- Agents MAY include a lightweight delivery snapshot when `include_snapshot=true`. The snapshot provides lifetime impressions and last-served date for operational use — detailed analytics belong in `get_creative_delivery`.
- Sales agents declaring `list_creatives` in `media_buy.relationship_notifications.projection_tasks` MUST scope creative advisories to `assignments.assigned_packages[].advisories[]`; they MUST NOT place package- or publisher-specific fatigue on the creative as a global property.
- Those sellers MUST include `media_buy_id` and `approval_status` on every assignment row, including rows whose advisory state is unknown. `rejection_reason` and `approval_scopes` mirror the media-buy projection. `advisory_types_evaluated` declares exact type coverage; `advisories_evaluated_scope` declares partial publisher/placement coverage.
- When the same relationship is visible through both reads, approval state, rejection reason, advisory types, scopes, detection times, evaluation coverage, and `advisories_as_of` MUST agree.
- Every advisory-capable seller accepts `advisories.changed` and may independently accept `creative.assignment_changed`, including when it is inline-only. These are prospective invalidations; receivers establish a complete all-status or known-ID baseline and repair through `get_media_buys` rather than treating payloads or the bounded reverse projection as complete relationship state.
- When `account` and `include_pricing=true` are provided, agents that charge MUST include `pricing_options` on each creative — an array of [`vendor-pricing-option`](https://adcontextprotocol.org/schemas/v3/core/vendor-pricing-option.json) objects. Vendors may offer multiple options per creative (volume tiers, context-specific rates, different pricing models).

**Account requirements:**
Expand Down
Loading
Loading