Push notification config (A2A)

A push notification config is the TaskPushNotificationConfig object an A2A client gives an agent so the agent can POST updates about a task to the client’s webhook, instead of the client keeping a connection open or polling.

Fields. url (the webhook, required), id (the config’s identifier), taskId, an optional token unique to the task or session, optional authentication with a scheme such as Bearer and its credentials, and tenant for multi-tenant agents. Version 1.0 flattened the object. In v0.3 the settings sat in a nested pushNotificationConfig, and authentication listed schemes as an array.

Setting one up. The agent must declare capabilities.pushNotifications: true, or every config operation fails with PushNotificationNotSupportedError (JSON-RPC -32003). A client can attach a config to its first message in configuration.taskPushNotificationConfig, leaving the task ID empty, or add one later with CreateTaskPushNotificationConfig. It manages configs with the Get, List and Delete operations, and a config lasts until the task ends or the client deletes it. From the specification’s example:

{
  "configuration": {
    "taskPushNotificationConfig": {
      "url": "https://client.example.com/webhook/a2a-notifications",
      "authentication": {"scheme": "Bearer", "credentials": "secure-client-token-for-task-aaa"}
    }
  }
}

Delivery. On an update, the agent POSTs a StreamResponse (a task, message, statusUpdate or artifactUpdate) with Content-Type: application/a2a+json and an Authorization header built from the config. Webhook calls use plain HTTP and the HTTP+JSON payload shapes, whatever binding the task uses. The agent must try at least once and may retry with exponential backoff. The client must answer with a 2xx status, should handle duplicates idempotently, and must check that the task ID is one it expects.

Security. Section 13.2 tells agents to validate webhook URLs against SSRF by rejecting private ranges, localhost and link-local addresses. It tells clients to verify every notification, use HTTPS, and issue a unique, single-purpose token per config. The A2A streaming guide adds a stronger option: the agent signs each notification as a JWT that the client checks against the agent’s JWKS.

Neighbouring terms. Streaming delivers the same events over an open connection, and GetTask fetches the full task after a notification arrives.