Skip to main content
V3 webhooks let an integration react when Apostra records an event. They are not a reporting export: use the delivery read when you need the current facts. A webhook is a signed prompt to make that read.

Register a webhook endpoint

Open the Webhook endpoints Page from a V3 MCP host to add and manage a public HTTPS endpoint. Endpoints belong to the registered buyer agent that creates them: another agent, including one acting in the same customer account, cannot list or change them. The Page is available through the existing V3 beta feature profile. Hosted Adclaw event automations are not available yet. The planned hosted integration handles event routing internally, without asking you for a public endpoint or signing secret. Registering an endpoint here does not enable event-driven Adclaw runs. Endpoints registered before this ownership model are customer-owned records. They keep their existing delivery behaviour but are no longer available in the Page. To register or manage an endpoint, use a registered buyer agent and create that agent’s endpoint.
  1. Enter the public HTTPS URL you control.
  2. Copy the signing secret when the Page displays it. It is shown once and is never returned by endpoint lists or later reads.
  3. Select Verify. Apostra sends a control challenge to the URL. A failed challenge keeps the endpoint pending so you can correct the receiver and retry it.
  4. Rotate a verified endpoint’s secret when needed. The previous key remains valid for 24 hours, so receivers can switch without dropping deliveries.
  5. Disable an endpoint to stop future delivery. Accounts can retain at most 25 endpoint records, including disabled records. Delete a disabled endpoint to recover capacity; deletion also retires its signing secret. You can then register that URL again as a new endpoint when you are ready to start over.
Registering and verifying an endpoint does not connect it to any events. A subscription selects the event types and scopes, then references one or more verified endpoint IDs. Do not use the older v2 X-Webhook-Signature contract for a V3 delivery. The two formats are incompatible.

Verify a delivery

Every V3 delivery is an HTTPS POST with these headers. For version v1, calculate the signature over the exact bytes below. Do not parse or re-serialize the JSON before calculating it.
Use the endpoint secret as the UTF-8 HMAC key and HMAC-SHA256 as the algorithm. The lowercase hexadecimal result is HEX_DIGEST in Apostra-Signature. Treat a delivery as invalid when a required header occurs more than once, the signature is not exactly the shape above, the key id is unknown, the HMAC does not match in constant time, or the timestamp differs from your clock by more than five minutes. Check the signature before parsing the body. Keep the raw occurrences of each header until you verify the request. A server adapter that flattens duplicate headers to one string cannot enforce this requirement. The reference helper therefore accepts an array of raw values for each required header, even when there is only one value.

Handle retries and replay

Apostra-Delivery-Id identifies one logical delivery. Its value and body stay the same on every retry. The timestamp and signature can change because each attempt is signed when Apostra sends it. After signature verification, store the pair of your endpoint ID and delivery ID in the same durable transaction that applies the event. Keep it for at least 30 days. If you receive the same pair again, return a 2xx response without processing the event twice. A duplicate is normally a retry after Apostra did not receive your earlier success response, not an error. Do not use the delivery ID to order events. When order matters, follow the event’s documented cursor or read the current resource.

Rotate a secret

The Webhook endpoints Page will show a newly created secret once. Store it before you leave the page. When you rotate it, Apostra begins signing new deliveries with the new key ID and keeps the previous key valid for exactly 24 hours. Your verifier must select the secret by kid and accept both keys for exactly 24 hours. Remove the old key after its expiry. Never log a secret or return it from a webhook handler.

Retry and success policy

A 2xx response is success. Apostra does not follow redirects. It retries network failures, timeouts, 408, 429, and 5xx responses up to eight times in 24 hours: the initial attempt, then approximately 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, and 24 hours later. Each delay has jitter. For 429, Apostra honours a valid Retry-After value when that still fits inside the 24-hour window. Other 4xx responses are final. A 410 Gone disables the endpoint immediately. After the final failed attempt, Apostra marks the delivery as failed and exposes it in endpoint health rather than silently dropping it.

Test vectors and helpers

The @scope3/agentic-contracts/webhooks reference TypeScript verifier and the @scope3/agentic-contracts/webhooks/vectors language-neutral fixture ship with the contracts package. The vectors cover a valid current key, a valid previous key during rotation, body tampering, unknown keys, each duplicate required header, a stale timestamp, missing or malformed required headers, an expired rotated key, and a retry with the same delivery ID. SDKs should run these exact vectors before shipping a verifier. See the V3 quickstart for the API-key connection flow that precedes endpoint registration.

Event catalog

Every event below is a compact invalidation. Use the named repair read for current details; the webhook never substitutes for the resource itself. Subscriptions may scope these events to an advertiser, campaign, media buy, or source and use one or more verified endpoint IDs. Delivery is subject to the account’s rollout entitlement. The event data identifies the changed field, provider-readback source, and whether the change is financial; use the repair read for values before taking action.

Subscribe to an event category

A registered buyer agent can subscribe a verified endpoint of its own to an event category. Use save_notification_config with an eventSubscription:
An agent has at most one subscription per category. The subscription belongs to the agent: it names an endpoint the same agent registered, and no other agent in the account can read or change it. Event subscriptions are part of the V3 beta feature profile. A new subscription starts when it is created or last enabled. It does not replay earlier events. The reporting, indicators and campaign categories are described below.

reporting.status_changed

Subscribe to the reporting category to receive changes to the reporting obligations for media buys your agent can read. The V3 event contains the AdCP notification in payload, including the obligation ID, new health and open issue IDs. Its repair read is get(kind: "media_buy", id, include: ["reporting_status"]).
The read returns open obligations, obligations that transitioned to complete in the last seven days, and the latest obligation for each reporting configuration and feed. Obligations first recorded as complete appear only when they are the latest for their configuration and feed. It sorts action-required, delayed and waiting obligations first, followed by the other states, with the most recent first within each group. It returns up to 50; obligationsOmitted counts the rest. If 50 other eligible obligations sort ahead of a changed obligation, it may be omitted. The event still identifies it and its new health. A failed read appears in unavailableIncludes. These notifications are delivered to V3 event subscriptions. AdCP account push delivery is not available yet; it will follow when account-level delivery authorization is in place.

campaign.progress.changed

Subscribe to the campaign category to learn when a campaign’s published Campaign Pulse verdict, optimization goal verdict, or delivery goal verdict changes. An event follows the published state, including a verdict appearing or clearing; a candidate that has not been published sends nothing. Number-only changes send nothing. The same transition for the same campaign and goal fires at most once in 24 hours. Changes made during one campaign evaluation share one event. The body identifies the campaign, changed parts (pulse, goals, or delivery), and affected goal scopes and their media-buy and package IDs. A Pulse-only event carries no buy references; the follow-up read lists the contributing buys. Goal references are ordered by campaign, media buy, then package, and by priority within each scope. The list holds at most 100 references; goalsOmitted counts the rest and is zero when none were omitted. Read the full current state with get(kind: "campaign", id, include: ["progress", "pulse"]). The event is a doorbell rather than a historical snapshot. For example, a changed package delivery verdict produces:
A buyer agent receives this event only while it can read the campaign’s advertiser. Apostra checks that access when it creates the delivery and before each attempt. New subscriptions do not replay events from before activation.

indicators.changed

A seller can assert indicators on a package, such as pacing_risk or inventory_shortfall_forecast. Apostra stores the latest set the seller reported, and you read it on each package of the media buy (see package pacing). indicators.changed tells you when the seller’s or Apostra’s assertions have changed, so you do not have to poll for them. What counts as a change. For each package, Apostra compares the indicator types each source asserts independently, and for each seller type the seller’s reason when it gives one:
  • An indicator type appearing or disappearing is a change. Apostra asserts pacing_risk when its published package delivery verdict is underdelivery; its assertion and clearance are tracked independently of the seller’s.
  • A change in a type’s reason is a change. The reason is the seller’s ext.scope3.reason, when it is a short lower-case token (letters, digits, _, . and -, at most 64 characters). The managed sales agent sends this token. A seller that sends none changes on indicator type alone, and the seller’s free text is never compared.
  • A change in numbers alone, such as a forecast, a score or a timestamp, is not a change. A change in which indicator types the seller evaluated, with no change in what it asserts, is not a change either.
When it fires.
  • A new state fires only after its source reports it on two evaluations in a row. A state that goes away after one evaluation fires nothing.
  • The same change for the same package fires at most once in 24 hours. If the state is still in place when the day is over, it fires then.
  • A package’s first reported state is the starting point and fires nothing. A read that changes nothing sends nothing.
Seller indicators currently come from the managed sales agent when it is connected to Google Ad Manager. Apostra evaluates package delivery separately; a withheld evaluation is unknown and does not clear an assertion. Who receives it. Apostra sends the event to your endpoint only while your agent can read the advertiser that owns the media buy. It checks this before every attempt, so an agent whose access to the advertiser has ended stops receiving the event, and a delivery already queued is not sent. The body. The event is a compact invalidation. It names the media buy that holds the package and the indicator types that changed. It does not carry the indicator state.
change.source identifies seller or apostra; older deliveries may omit it. In the AdCP notification, Apostra-origin changes are marked by ext.apostra.source: "apostra"; the core AdCP change fields keep their normal meaning. occurredAt is when that source completed the evaluation that confirmed the change. eventId is the same on every retry. Verify the delivery. Event subscription deliveries are signed with Standard Webhooks, not with the Apostra-Signature header above. Each delivery carries webhook-id, webhook-timestamp and webhook-signature, plus X-MCP-Subscription-Id with the ID of the subscription that receives it. The signed bytes are webhook-id + "." + webhook-timestamp + "." + the raw request body. The HMAC key is the endpoint secret, base64-decoded after its whsec_ prefix, and webhook-signature holds one or more space-separated v1,BASE64_HMAC_SHA256 values. Check the signature and a timestamp within your replay window before parsing the body, and deduplicate by webhook-id. Retries follow the retry policy above and keep the same webhook-id and body.