Push Notifications

create_media_buy request
  └── push_notification_config
        └── url: "https://you.com/adcp/webhook/create_media_buy/agent_123/route_abc123"
        └── operation_id: "op_456"
              // No shared secret — the seller signs with its own key, you verify against
              // its published JWKS. See "Signature verification" below.

              ↓ seller processes task ↓

POST https://you.com/adcp/webhook/create_media_buy/agent_123/route_abc123
  Signature-Input: sig1=("@method" "@target-uri" "@authority" "content-type" "content-digest");
                   created=1706097600;expires=1706097900;nonce="...";keyid="seller-webhook-2025";
                   alg="ed25519";tag="adcp/webhook-signing/v1"
  Signature: sig1=:<base64url-unpadded>:
  Content-Digest: sha-256=:<base64url-unpadded>:
  Content-Type: application/json

  {
    "idempotency_key": "whk_01HW9D3H8FZP2N6R8T0V4X6Z9B",   ← dedup by this
    "task_id": "task_456",
    "operation_id": "op_456",   ← echoed from push_notification_config.operation_id
    "status": "completed",
    "result": { ... }
  }

{
  "brand": { "brand_id": "acme" },
  "start_time": { "type": "date", "date": "2025-03-01" },
  "end_time": "2025-06-30T23:59:59Z",
  "packages": [...],
  "push_notification_config": {
    "url": "https://you.com/webhooks/adcp/create_media_buy/route_abc123",
    "operation_id": "op_abc123"
  }
}

{
  "message": {
    "parts": [{
      "kind": "data",
      "data": {
        "skill": "create_media_buy",
        "parameters": {
          "packages": [...]
        }
      }
    }]
  },
  "configuration": {
    "pushNotificationConfig": {
      "url": "https://you.com/webhooks/adcp/create_media_buy/route_abc123",
      "operation_id": "op_abc123"
    }
  }
}

https://you.com/webhooks/{task_type}/{agent_id}/{route_token}

import { randomUUID } from 'crypto';

const operationId = randomUUID(); // e.g. "cd51e063-2b79-4a6d-afac-ed7789c3a443"
const routeId = randomUUID(); // receiver-local routing token; opaque to the seller
const webhookUrl = `https://you.com/adcp/webhook/create_media_buy/${agentId}/${routeId}`;

// pass both webhookUrl and operationId in push_notification_config

{
  "idempotency_key": "whk_01HW9D3H8FZP2N6R8T0V4X6Z9B",
  "task_id": "task_456",
  "operation_id": "cd51e063-2b79-4a6d-afac-ed7789c3a443",
  "task_type": "create_media_buy",
  "domain": "media-buy",
  "status": "completed",
  "timestamp": "2025-01-22T10:30:00Z",
  "message": "Media buy created successfully",
  "result": {
    "media_buy_id": "mb_12345",
    "packages": [
      { "package_id": "pkg_001", "context": { "line_item": "li_ctv_sports" } }
    ]
  }
}

{
  "idempotency_key": "whk_20260526_example_000031",
  "operation_id": "delivery_report_67_2026_04",
  "task_id": "delivery_report_67_2026_04_000031",
  "task_type": "media_buy_delivery",
  "status": "completed",
  "timestamp": "2026-05-26T09:00:44.582Z",
  "message": "Scheduled media buy delivery report available",
  "result": {
    "notification_type": "scheduled",
    "sequence_number": 31,
    "reporting_period": {
      "start": "2026-05-25T00:00:00Z",
      "end": "2026-05-25T23:59:00Z"
    },
    "currency": "USD",
    "media_buy_deliveries": [
      {
        "media_buy_id": "mb_001",
        "status": "active",
        "totals": {
          "impressions": 125000,
          "spend": 5625.0,
          "clicks": 250
        },
        "by_package": []
      }
    ]
  }
}

{
  "notification_type": "scheduled",
  "sequence_number": 31,
  "reporting_period": {
    "start": "2026-05-25T00:00:00Z",
    "end": "2026-05-25T23:59:00Z"
  },
  "currency": "USD",
  "media_buy_deliveries": []
}

{
  "id": "task_456",
  "contextId": "ctx_123",
  "status": {
    "state": "completed",
    "timestamp": "2025-01-22T10:30:00Z"
  },
  "artifacts": [{
    "artifactId": "result",
    "parts": [
      { "kind": "text", "text": "Media buy created successfully" },
      {
        "kind": "data",
        "data": {
          "media_buy_id": "mb_12345",
          "packages": [
            { "package_id": "pkg_001", "context": { "line_item": "li_ctv_sports" } }
          ]
        }
      }
    ]
  }]
}

Signature-Input: sig1=("@method" "@target-uri" "@authority" "content-type" "content-digest");
                 created=<unix>;expires=<unix>;nonce=<base64url>;
                 keyid=<kid>;alg="ed25519";tag="adcp/webhook-signing/v1"
Signature: sig1=:<base64url-unpadded>:
Content-Digest: sha-256=:<base64url-unpadded>:

import { createRemoteJWKSet, jwtVerify } from 'jose';
// Use a validated RFC 9421 library (e.g., `http-message-signatures`) pinned to the AdCP profile.

app.post('/webhooks/adcp/*', async (req, res) => {
  try {
    // 1. Parse Signature-Input / Signature headers and reject on malformed.
    // 2. Resolve keyid against the seller operator's brand.json JWKS.
    // 3. Run the AdCP webhook verifier checklist (14 steps).
    await verifyAdcpWebhookSignature(req, {
      sellerAgentUrl: req.sellerContext.agentUrl, // known from your integration
      requiredTag: 'adcp/webhook-signing/v1',
      allowedAlgs: ['ed25519', 'ecdsa-p256-sha256'],
    });
  } catch (err) {
    return res.status(401)
      .setHeader('WWW-Authenticate', `Signature error="${err.code}"`)
      .end();
  }

  // 4. Dedup by idempotency_key before applying side effects (see Reliability below).
  processWebhook(req.body);
  res.status(200).end();
});

app.use(express.json({
  verify: (req, _res, buf) => { (req as any).rawBody = buf.toString('utf-8'); },
}));

{
  "authentication": {
    "schemes": ["HMAC-SHA256"],
    "credentials": "your_shared_secret_min_32_chars"
  }
}

X-ADCP-Signature: sha256=<hex digest>
X-ADCP-Timestamp: <unix timestamp in seconds>

Signature = sha256= + hex( HMAC-SHA256( secret, "{timestamp}.{rawBody}" ) )

import { createHmac } from 'crypto';

function signWebhook(rawBody: string, secret: string): { signature: string; timestamp: string } {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const message = `${timestamp}.${rawBody}`;
  const hex = createHmac('sha256', secret).update(message).digest('hex');
  return { signature: `sha256=${hex}`, timestamp };
}

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(
  rawBody: string, signature: string, timestamp: string, secret: string,
): boolean {
  const ts = parseInt(timestamp, 10);
  if (isNaN(ts)) return false;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > 300) return false;

  const message = `${ts}.${rawBody}`;
  const expected = `sha256=${createHmac('sha256', secret).update(message).digest('hex')}`;
  if (signature.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

{
  "authentication": {
    "schemes": ["Bearer"],
    "credentials": "your_bearer_token_min_32_chars"
  }
}

app.post('/webhooks/adcp', (req, res) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (token !== process.env.ADCP_WEBHOOK_TOKEN) return res.status(401).end();
  processWebhook(req.body);
  res.status(200).end();
});

app.post('/webhooks/adcp', async (req, res) => {
  const payload = req.body;
  const { idempotency_key, task_id, status, timestamp, result } = payload;

  // Scope dedup to the authenticated sender — never trust a payload field for identity.
  const sender = req.verifiedSenderId; // set by 9421 verifier (keyid → agent URL) or legacy HMAC/Bearer middleware

  // Dedup: same (sender, idempotency_key) within the replay window → already processed.
  // Return 200 (not 409) so the sender stops retrying.
  if (await db.webhookAlreadyProcessed(sender, idempotency_key)) {
    return res.status(200).end();
  }
  await db.markWebhookProcessed(sender, idempotency_key); // before side effects — fail-closed on crash

  // Ordering: separately, don't apply a stale status on top of a newer one.
  // Ordering state is keyed on task_id, not idempotency_key — two distinct events
  // (different keys) can still arrive out of order. Still a 200: we received it cleanly.
  const task = await db.getTask(task_id);
  if (task?.updated_at >= timestamp) {
    return res.status(200).end();
  }

  await db.updateTask(task_id, { status, updated_at: timestamp, result });
  await triggerBusinessLogic(task_id, status);
  res.status(200).end();
});

function extractAdcpResponseFromWebhook(payload, knownFormat) {
  const format = knownFormat || detectFormat(payload);

  if (format === 'mcp') return payload.result ?? null;
  if (format === 'a2a') return extractAdcpResponseFromA2A(payload);
  return null;
}

function detectFormat(payload) {
  if (payload.status && typeof payload.status === 'object'
      && !Array.isArray(payload.status) && payload.status.state) return 'a2a';
  if (typeof payload.status === 'string' && payload.task_id) return 'mcp';
  return null;
}