> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook endpoints

> Register endpoints and verify signed Apostra webhook deliveries.

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.

| Header | Value |
| - | - |
| `Apostra-Signature` | `v1,kid=SECRET_ID,hmac-sha256=HEX_DIGEST` |
| `Apostra-Timestamp` | Unix timestamp in whole seconds |
| `Apostra-Delivery-Id` | An opaque, retry-stable delivery identifier |

For version `v1`, calculate the signature over the exact bytes below. Do not
parse or re-serialize the JSON before calculating it.

```text theme={null}
UTF-8("v1." + Apostra-Timestamp + "." + Apostra-Delivery-Id + ".") + raw request body bytes
```

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](https://docs.apostra.com/v3/quickstart.md) 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.

| Event | Fires when | Repair read |
| - | - | - |
| `media_buy.status_changed` | A provider readback changes a media buy status | `get(kind: "media_buy", id)` |
| `media_buy.budget_changed` | A provider readback changes a media buy budget | `get(kind: "media_buy", id)` |
| `media_buy.flight_changed` | A provider readback changes a media buy flight | `get(kind: "media_buy", id)` |
| `media_buy.creative_changed` | A provider readback changes creative state | `get(kind: "media_buy", id)` |
| `media_buy.targeting_changed` | A provider readback changes targeting | `get(kind: "media_buy", id)` |
| `media_buy.object_discovered` | A provider readback discovers a media buy | `search(kind: "media_buy")` |

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`:

```json theme={null}
{
  "eventSubscription": {
    "action": "create",
    "subscription": {
      "category": "indicators",
      "endpointId": "<verified endpoint ID>",
      "delivery": { "mode": "every_update" }
    }
  }
}
```

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 `indicators` category is the only category described on this page.

### `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](https://docs.apostra.com/v3/package-pacing.md#see-what-the-seller-says-about-a-package)).
`indicators.changed` tells you that set has changed, so you do not have to poll
for it.

| Event | Fires when | Repair read |
| - | - | - |
| `indicators.changed` | A package's seller indicators change and the change has held | `get(kind: "media_buy", id, include: ["products"])`, then each package |

**What counts as a change.** For each package, Apostra compares the indicator
types the seller asserts, and for each type the seller's reason when it gives
one:

* An indicator type appearing or disappearing is a change.
* 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 the seller 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.

Today Apostra reads indicators from the managed sales agent when it is
connected to Google Ad Manager, so these are the packages that produce the
event.

**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.

```json theme={null}
{
  "version": "v3.event.v1",
  "eventId": "c1e45224-7b68-48e5-869d-6f9d97f32063",
  "subscriptionId": "3ab80c76-9fa7-4db8-84f5-fdca982df8f7",
  "occurredAt": "2026-11-07T10:15:00.000Z",
  "category": "indicators",
  "type": "indicators.changed",
  "resource": { "kind": "media_buy", "id": "mb_42" },
  "change": { "kind": "indicator_set", "indicatorTypes": ["pacing_risk"] },
  "repair": { "tool": "get", "arguments": { "kind": "media_buy", "id": "mb_42" } }
}
```

`occurredAt` is when the seller 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](https://www.standardwebhooks.com/), 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](https://docs.apostra.com/v3/webhooks.md#retry-and-success-policy) above and keep the same `webhook-id`
and body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.