feat: production-ready webhook security and reliability for reporting

docs/media-buy/task-reference/create_media_buy.md

@@ -821,19 +821,69 @@ For MCP implementations using polling, use this endpoint to check the status of
 
 #### Option 2: Webhooks (MCP)
 
-Register a callback URL to receive push notifications:
-```json
-{
-  "tool": "create_media_buy",
-  "arguments": {
-    "buyer_ref": "campaign_2024",
-    "packages": [...],
-    "webhook_url": "https://buyer.example.com/mcp/webhooks",
-    "webhook_auth_token": "bearer-token-xyz"
+Register a callback URL to receive push notifications for long-running operations. Webhooks are ONLY used when the initial response is `submitted`.
+
+**Configuration:**
+```javascript
+const response = await session.call('create_media_buy',
+  {
+    buyer_ref: "campaign_2024",
+    packages: [...]
+  },
+  {
+    webhook_url: "https://buyer.example.com/webhooks/adcp/create_media_buy/agent_id/op_id",
+    webhook_auth: { type: "bearer", credentials: "bearer-token-xyz" }
   }
+);
+```
+
+**Response patterns:**
+- **`completed`** - Synchronous success, webhook NOT called (you have the result)
+- **`working`** - Will complete within ~120s, webhook NOT called (wait for response)
+- **`submitted`** - Long-running operation, webhook WILL be called on status changes
+
+**Example webhook flow (only for `submitted` operations):**
+
+Webhook POST for human approval needed:
+```http
+POST /webhooks/adcp/create_media_buy/agent_id/op_id HTTP/1.1
+Host: buyer.example.com
+Authorization: Bearer bearer-token-xyz
+Content-Type: application/json
+
+{
+  "adcp_version": "1.6.0",
+  "status": "input-required",
+  "task_id": "task_456",
+  "buyer_ref": "campaign_2024",
+  "message": "Campaign budget $150K requires approval to proceed"
+}
+```
+
+**Webhook POST when complete (after approval - full create_media_buy response):**
+```http
+POST /webhooks/adcp/create_media_buy/agent_id/op_id HTTP/1.1
+Host: buyer.example.com
+Authorization: Bearer bearer-token-xyz
+Content-Type: application/json
+
+{
+  "adcp_version": "1.6.0",
+  "status": "completed",
+  "media_buy_id": "mb_12345",
+  "buyer_ref": "campaign_2024",
+  "creative_deadline": "2024-01-30T23:59:59Z",
+  "packages": [
+    {
+      "package_id": "pkg_001",
+      "buyer_ref": "ctv_package"
+    }
+  ]
 }
 ```
 
+Each webhook receives the full response object for that status. See **[Task Management: Webhook Integration](../../protocols/task-management.md#webhook-integration)** for complete details.
+
 ### A2A Status Checking
 
 A2A supports both SSE streaming and webhooks as shown in the examples above. Choose based on your needs:

docs/media-buy/task-reference/sync_creatives.md

@@ -32,6 +32,7 @@ The `sync_creatives` task provides a powerful, efficient approach to creative li
 | `patch` | boolean | No | Partial update mode (default: false) |
 | `dry_run` | boolean | No | Preview changes without applying (default: false) |
 | `validation_mode` | enum | No | Validation strictness: "strict" or "lenient" (default: "strict") |
+| `push_notification_config` | PushNotificationConfig | No | Optional webhook for async sync notifications (see Webhook Configuration below) |
 
 ### Assignment Management
 
@@ -60,6 +61,34 @@ Each creative in the `creatives` array follows the [Creative Asset schema](/sche
 - `snippet_type: "html"`
 - `assets` array with sub-assets for template variables
 
+## Webhook Configuration (Task-Specific)
+
+For large bulk operations or creative approval workflows, you can provide a task-specific webhook to be notified when the sync completes:
+
+```json
+{
+  "creatives": [/* up to 100 creatives */],
+  "push_notification_config": {
+    "url": "https://buyer.com/webhooks/creative-sync",
+    "authentication": {
+      "schemes": ["HMAC-SHA256"],
+      "credentials": "shared_secret_32_chars"
+    }
+  }
+}
+```
+
+**When webhooks are sent:**
+- Bulk sync takes longer than ~120 seconds (status: `working` → `completed`)
+- Creative approval required (status: `submitted` → `completed`)
+- Large creative uploads processing asynchronously
+
+**Webhook payload:**
+- Complete sync_creatives response with summary and results
+- Includes action taken for each creative (created/updated/unchanged/failed)
+
+See [Webhook Security](../../protocols/core-concepts.md#security) for authentication details.
+
 ## Response Format
 
 The response provides comprehensive details about the sync operation:

docs/media-buy/task-reference/update_media_buy.md

@@ -24,6 +24,7 @@ Update campaign and package settings. This task supports partial updates and han
 | `end_time` | string | No | New end date/time in ISO 8601 format (UTC unless timezone specified) |
 | `budget` | Budget | No | New budget configuration (see Budget Object in create_media_buy) |
 | `packages` | PackageUpdate[] | No | Package-specific updates (see Package Update Object below) |
+| `push_notification_config` | PushNotificationConfig | No | Optional webhook for async update notifications (see Webhook Configuration below) |
 
 *Either `media_buy_id` or `buyer_ref` must be provided
 
@@ -40,6 +41,37 @@ Update campaign and package settings. This task supports partial updates and han
 
 *Either `package_id` or `buyer_ref` must be provided
 
+## Webhook Configuration (Task-Specific)
+
+For long-running updates (typically requiring approval workflows), you can provide a task-specific webhook to be notified when the update completes:
+
+```json
+{
+  "buyer_ref": "nike_q1_campaign_2024",
+  "budget": {
+    "total": 150000,
+    "currency": "USD"
+  },
+  "push_notification_config": {
+    "url": "https://buyer.com/webhooks/media-buy-updates",
+    "authentication": {
+      "schemes": ["HMAC-SHA256"],
+      "credentials": "shared_secret_32_chars"
+    }
+  }
+}
+```
+
+**When webhooks are sent:**
+- Update requires manual approval (status: `submitted` → `completed`)
+- Update takes longer than ~120 seconds (status: `working` → `completed`)
+
+**Webhook payload:**
+- Complete update_media_buy response with final status
+- Includes media_buy_id, affected_packages, and implementation_date
+
+See [Webhook Security](../../protocols/core-concepts.md#security) for authentication details.
+
 ## Response (Message)
 
 The response includes a human-readable message that: