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.- Enter the public HTTPS URL you control.
- Copy the signing secret when the Page displays it. It is shown once and is never returned by endpoint lists or later reads.
- 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.
- Rotate a verified endpoint’s secret when needed. The previous key remains valid for 24 hours, so receivers can switch without dropping deliveries.
- 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.
X-Webhook-Signature contract for a V3 delivery. The
two formats are incompatible.
Verify a delivery
Every V3 delivery is an HTTPSPOST 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.
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 bykid 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
A2xx 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. Usesave_notification_config with an eventSubscription:
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"]).
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:
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_riskwhen 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.
- 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.
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.