Skip to content

docs(spec): Rename PushNotificationConfig to TaskPushNotificationConfig #1981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Iwaniukooo11 wants to merge 2 commits into
base: main
Choose a base branch
from
+18 −20
Open

docs(spec): Rename PushNotificationConfig to TaskPushNotificationConfig #1981

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
944231c
docs: Rename PushNotificationConfig to TaskPushNotificationConfig for…
Iwaniukooo11 Jun 24, 2026
2b783fe
remove duplicate rendering 10.4.7
Iwaniukooo11 Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 10 additions & 12 deletions docs/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Creates a push notification configuration for a task to receive asynchronous upd

**Outputs:**

- [`PushNotificationConfig`](#431-pushnotificationconfig): Created configuration with assigned ID
- [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig): Created configuration with assigned ID

**Errors:**

Expand All @@ -348,7 +348,7 @@ Retrieves an existing push notification configuration for a task.

**Outputs:**

- [`PushNotificationConfig`](#431-pushnotificationconfig): The requested configuration
- [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig): The requested configuration

**Errors:**

Expand Down Expand Up @@ -827,11 +827,11 @@ The A2A protocol defines a canonical data model using Protocol Buffers. All prot

### 4.3. Push Notification Objects

<a id="PushNotificationConfig"></a>
<a id="TaskPushNotificationConfig"></a>

#### 4.3.1. PushNotificationConfig
#### 4.3.1. TaskPushNotificationConfig

{{ proto_to_table("PushNotificationConfig") }}
{{ proto_to_table("TaskPushNotificationConfig") }}

<a id="PushNotificationAuthenticationInfo"></a>

Expand Down Expand Up @@ -870,7 +870,7 @@ The webhook payload is a [`StreamResponse`](#323-stream-response) object contain

**Authentication:**

The agent MUST include authentication credentials in the request headers as specified in the [`PushNotificationConfig.authentication`](#432-authenticationinfo) field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).
The agent MUST include authentication credentials in the request headers as specified in the [`TaskPushNotificationConfig.authentication`](#432-authenticationinfo) field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).

**Client Responsibilities:**

Expand Down Expand Up @@ -2618,11 +2618,9 @@ Subscribe to task updates via streaming. Returns `UnsupportedOperationError` if

Creates a push notification configuration for a task.

**Request:**

{{ proto_to_table("CreateTaskPushNotificationConfigRequest") }}
**Request:** See [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig) object definition.

**Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition.
**Response:** See [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig) object definition.

#### 10.4.8. GetTaskPushNotificationConfig

Expand All @@ -2632,7 +2630,7 @@ Retrieves an existing push notification configuration for a task.

{{ proto_to_table("GetTaskPushNotificationConfigRequest") }}

**Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition.
**Response:** See [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig) object definition.

#### 10.4.9. ListTaskPushNotificationConfigs

Expand Down Expand Up @@ -3127,7 +3125,7 @@ When implementing push notifications, both agents (as webhook callers) and clien
**Configuration Security:**

- Webhook URLs **SHOULD** use HTTPS to protect payload confidentiality in transit
- Authentication tokens in [`PushNotificationConfig`](#431-pushnotificationconfig) **SHOULD** be treated as secrets and rotated periodically
- Authentication tokens in [`TaskPushNotificationConfig`](#431-taskpushnotificationconfig) **SHOULD** be treated as secrets and rotated periodically
- Agents **SHOULD** securely store push notification configurations and credentials
- Clients **SHOULD** use unique, single-purpose tokens for each push notification configuration

Expand Down
16 changes: 8 additions & 8 deletions docs/topics/streaming-and-async.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,12 @@ For very long-running tasks (for example, lasting minutes, hours, or even days)
The following key features detail how push notifications are implemented and managed within the A2A protocol:

- **Server Capability:** The A2A Server must indicate its support for this feature by setting `capabilities.pushNotifications: true` in its Agent Card.
- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#pushnotificationconfig) to the server. This configuration is supplied:
- **Configuration:** The client provides a [`TaskPushNotificationConfig`](../specification.md#431-taskpushnotificationconfig) to the server. This configuration is supplied:
- Within the initial `SendMessage` or `SendStreamingMessage` request, or
- Separately, using the `CreateTaskPushNotificationConfig` RPC method for an existing task.
The `PushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
The `TaskPushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
- **Notification Trigger:** The A2A Server decides when to send a push notification, typically when a task reaches a significant state change (for example, terminal state, `input-required`, or `auth-required`).
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#pushnotificationpayload) for detailed structure.
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#433-push-notification-payload) for detailed structure.
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `GetTask` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.

### When to Use Push Notifications
Expand All @@ -72,7 +72,7 @@ Refer to the Protocol Specification for detailed structures:

### Client-Side Push Notification Service

The `url` specified in `PushNotificationConfig.url` points to a client-side Push Notification Service. This service is responsible for receiving the HTTP POST notification from the A2A Server. Its responsibilities include authenticating the incoming notification, validating its relevance, and relaying the notification or its content to the appropriate client application logic or system.
The `url` specified in `TaskPushNotificationConfig.url` points to a client-side Push Notification Service. This service is responsible for receiving the HTTP POST notification from the A2A Server. Its responsibilities include authenticating the incoming notification, validating its relevance, and relaying the notification or its content to the appropriate client application logic or system.

### Security Considerations for Push Notifications

Expand All @@ -82,20 +82,20 @@ Security is paramount for push notifications due to their asynchronous and serve

- **Webhook URL Validation:** Servers SHOULD NOT blindly trust and send POST requests to any URL provided by a client. Malicious clients could provide URLs pointing to internal services or unrelated third-party systems, leading to Server-Side Request Forgery (SSRF) attacks or acting as Distributed Denial of Service (DDoS) amplifiers.
- **Mitigation strategies:** Allowlisting of trusted domains, ownership verification (for example, challenge-response mechanisms), and network controls (e.g., egress firewalls).
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme specified in `TaskPushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).

#### Client Webhook Receiver Security (when receiving notifications from A2A server)

- **Authenticating the A2A Server:** The webhook endpoint MUST rigorously verify the authenticity of incoming notification requests to ensure they originate from the legitimate A2A Server and not an imposter.
- **Verification methods:** Verify signatures/tokens (for example, JWT signatures against the A2A Server's trusted public keys, HMAC signatures, or API key validation). Also, validate the `PushNotificationConfig.token` if provided.
- **Verification methods:** Verify signatures/tokens (for example, JWT signatures against the A2A Server's trusted public keys, HMAC signatures, or API key validation). Also, validate the `TaskPushNotificationConfig.token` if provided.
- **Preventing Replay Attacks:**
- **Timestamps:** Notifications SHOULD include a timestamp. The webhook SHOULD reject notifications that are too old.
- **Nonces/unique IDs:** For critical notifications, consider using unique, single-use identifiers (for example, JWT's `jti` claim or event IDs) to prevent processing duplicate notifications.
- **Secure Key Management and Rotation:** Implement secure key management practices, including regular key rotation, especially for cryptographic keys. Protocols like JWKS (JSON Web Key Set) facilitate key rotation for asymmetric keys.

#### Example Asymmetric Key Flow (JWT + JWKS)

1. Client creates a `PushNotificationConfig` specifying `authentication.scheme: "Bearer"` and possibly an expected `issuer` or `audience` for the JWT.
1. Client creates a `TaskPushNotificationConfig` specifying `authentication.scheme: "Bearer"` and possibly an expected `issuer` or `audience` for the JWT.
2. A2A Server, when sending a notification:
- Generates a JWT, signing it with its private key. The JWT includes claims like `iss` (issuer), `aud` (audience), `iat` (issued at), `exp` (expires), `jti` (JWT ID), and `taskId`.
- The JWT header indicates the signing algorithm and key ID (`kid`).
Expand All @@ -106,6 +106,6 @@ Security is paramount for push notifications due to their asynchronous and serve
- Fetches the corresponding public key from the A2A Server's JWKS endpoint (caching keys is recommended).
- Verifies the JWT signature using the public key.
- Validates claims (`iss`, `aud`, `iat`, `exp`, `jti`).
- Checks the `PushNotificationConfig.token` if provided.
- Checks the `TaskPushNotificationConfig.token` if provided.

This comprehensive, layered approach to security for push notifications helps ensure that messages are authentic, integral, and timely, protecting both the sending A2A Server and the receiving client webhook infrastructure.
Loading