create_media_buy, update_media_buy, sync_creatives or media_buy_delivery, the call includes
a push_notification_config. It says where to push the result and how to sign it. We reject an
unsigned or wrongly signed callback with 401, and the task is never resolved. A refused delivery
changes nothing on our side.
This page covers callbacks you send to Apostra. To verify the events Apostra sends to your own
endpoints, see Webhook endpoints; that is a different scheme. To send
delivery reports, see Deliver reporting to Apostra.
Choose a profile
You can sign with one of three profiles, strongest first:
HMAC is deprecated in AdCP and removed in 4.0. AdCP 3.3 deprecates
brand.json key discovery, and
4.0 removes it, so new agents should sign with Web Bot Auth.
AdCP 3.3 Web Bot Auth
With Web Bot Auth, each delivery names its signer in theSignature-Agent header, and we fetch your public keys from
that origin’s key directory. We accept it on:
sync_creativescallbacks registered for RFC 9421 (see Creative-sync callbacks below);- storefront inventory-source callbacks;
create_media_buyandupdate_media_buycallbacks, andmedia_buy_deliveryreports, to a sales agent’s callback URL.
brand.json profile only for now.
To sign with Web Bot Auth:
- Publish a signed key directory at
/.well-known/http-message-signatures-directoryon the origin of your agent endpoint, the endpoint we have on file for your agent or source. - On each delivery, send
Signature-Agentwith your agent’s origin, plusSignature-Input(taggedweb-bot-auth) andSignature. - Cover
@method,@target-uri,@authorityandsignature-agent, and, when the callback has a body,content-typeandcontent-digest. - Use a fresh
nonceon every delivery attempt, including a retry, and keepexpireswithin 300 seconds ofcreated. - Optionally publish an origin revocation list at
/.well-known/governance-revocations.json. We refuse a key on that list.
- Origin. The origin in
Signature-Agentmust be the origin of the endpoint we registered for that agent or source. A signature from another agent’s directory, or from a different origin of your operator, gets401, however valid it is. - URL. The
@target-uriyou sign must be the callback URL exactly as we sent it inpush_notification_config.url, query string included. A signature made for one operation fails on any other. - Replay. A nonce we have already accepted gets
401. We record a nonce only after every check that could answer503has passed, so redelivering after a503is always safe, provided the retry is signed afresh.
RFC 9421 with brand.json keys
To sign the AdCP 3.2 webhook profile with RFC 9421 HTTP Message Signatures, you need:- An https agent endpoint that answers
get_adcp_capabilitieswithout credentials, over the protocol you registered with us (MCP or A2A). Your capabilities tell us where yourbrand.jsonlives. - A
brand.jsonwhoseagents[]entry for your endpoint has the same URL as the endpoint we call and declares ajwks_uri. SignatureandSignature-Inputheaders on each delivery. Always send both: aSignaturewith noSignature-Inputis refused rather than checked as HMAC.
brand.json like this:
- If your capabilities declare
identity.brand_json_url, we fetch that https URL. When it is on a different registrable domain from your agent, it must list your agent’s domain inauthorized_operators[]. - An AdCP 3.x agent that declares no
identity.brand_json_urlis looked up at/.well-known/brand.jsonon its origin, then on its registrable domain if that returns404or410. We follow at most oneauthoritative_locationorhouseredirect. - An AdCP 4.0 agent must declare
identity.brand_json_url.
HMAC-SHA256
Sign with theauthentication.credentials value from the push_notification_config on the call you
are answering. It is unique to that callback URL: it is not your Apostra API key, and a sales agent
that is also an inventory source receives a different value on each.
Send two headers:
Serialize the body once and sign the exact bytes you send. We allow 300 seconds of clock skew.
@adcp/sdk webhook emitter produces this signature when
the push_notification_config declares HMAC-SHA256.
When we send no HMAC credential
We choose the scheme for each call that carries a callback from the capabilities we have stored for your agent. Your agent is treated as signing whenwebhook_signing.supported is true and either:
- your agent declares
identity.brand_json_url(AdCP 3.2 RFC 9421 withbrand.jsonkeys), or webhook_signing.profilesincludesweb-bot-auth(AdCP 3.3 Web Bot Auth), with nobrand.jsonneeded.
Creative-sync callbacks
- An HMAC delivery to a URL we registered without a credential gets
401. - An RFC 9421 or Web Bot Auth delivery for a call that carried a credential gets
401. - To go back to HMAC, set
webhook_signing.supportedtofalse, or remove theweb-bot-authprofile andidentity.brand_json_url, unless your origin has already signed with Web Bot Auth.
Media-buy and reporting callbacks
Forcreate_media_buy, update_media_buy and the delivery reports registered with them, a signing
agent that serves AdCP 3.3 when we call it, and says then that it signs webhooks, gets no
authentication block. The push_notification_config and the reporting_webhook carry a
signing_profile instead, and you sign every callback with that profile. Any other agent keeps the
HMAC credential: AdCP 3.2 requires authentication on reporting_webhook, so we send it to agents
that serve 3.2. Both kinds of callback are accepted signed or with the credential they were sent.
Responses
If callbacks are rejected
A401 never says which check failed, so it cannot be used to probe the
verifier. Work through these first, in the order they most often cause it:
- Every callback has always been rejected. Almost always the wrong key.
Sign with
authentication.credentialsfrom thepush_notification_configon the call you are answering, not an API key, an onboarding secret, or a credential stored from a different registration. If you are registered on more than one rail, each rail has its own key. - Callbacks were working and stopped. Check clock drift on the sending host. Outside the 300-second window every callback fails whatever the digest. Also check that the timestamp did not become milliseconds in a refactor.
- The digest looks right but fails. Something re-serialized the body between signing and sending. Middleware that reformats JSON, adds a trailing newline or re-encodes a buffer changes the bytes. Sign the exact string you write to the socket.
- The header is the wrong shape. The value must be
sha256=plus lowercase hex. Base64, uppercase hex and a bare digest with no prefix are all refused.