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

# Push notifications

# Push Notifications

Push notifications are the A2A protocol's mechanism for delivering task updates to disconnected clients. When a client submits a long-running task and can't maintain a persistent connection, it provides a webhook URL and Svantic POSTs task state changes to that URL.

This is distinct from [Svantic's notification channels](./notifications), which are policy-linked delivery endpoints for human alerts. Push notifications are per-task, caller-specified, and part of the A2A standard.

***

## When to Use Push Notifications

| Scenario                                      | Recommended Approach                                                    |
| --------------------------------------------- | ----------------------------------------------------------------------- |
| Short task, client waiting                    | `message/send` (synchronous) — response comes in the same HTTP request  |
| Interactive session, real-time updates        | `message/stream` (SSE) — events streamed as they happen                 |
| Long-running task, client can hold connection | `message/stream` (SSE) — persistent connection with incremental updates |
| Long-running task, client disconnects         | **Push notifications** — POST updates to callback URL                   |
| Fire-and-forget from serverless/mobile        | **Push notifications** — no persistent connection possible              |
| External orchestrator submitting tasks        | **Push notifications** — orchestrator polls or receives callbacks       |

Push notifications are ideal when the client **cannot or prefers not to maintain** a persistent connection. Mobile apps, serverless functions, and batch job schedulers are common use cases.

***

## How It Works

### 1. Client Provides Push Config

When sending a message, the client includes a `PushNotificationConfig`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "kind": "text", "text": "Generate quarterly compliance report" }]
    },
    "configuration": {
      "pushNotificationConfig": {
        "url": "https://my-system.example.com/a2a-callback",
        "token": "task-unique-token-abc",
        "authentication": {
          "schemes": ["bearer"],
          "credentials": "my-bearer-token"
        }
      }
    }
  }
}
```

| Field            | Required | Purpose                                                                                                                             |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `url`            | Yes      | HTTPS endpoint where Svantic will POST task updates                                                                                 |
| `token`          | No       | Opaque token Svantic includes in the notification header — lets the receiver validate the notification belongs to the expected task |
| `authentication` | No       | How Svantic authenticates to the webhook — scheme + credentials                                                                     |

### 2. Svantic POSTs State Changes

On every significant state transition, Svantic sends an HTTP POST to the configured URL:

```http theme={null}
POST https://my-system.example.com/a2a-callback
Content-Type: application/json
X-A2A-Notification-Token: task-unique-token-abc
Authorization: Bearer my-bearer-token

{
  "jsonrpc": "2.0",
  "method": "task/statusUpdate",
  "params": {
    "id": "task-uuid-123",
    "status": {
      "state": "input-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "parts": [
          {
            "kind": "data",
            "data": { "type": "Form", "props": { "title": "Approval Required", "..." : "..." } },
            "metadata": { "mimeType": "application/json+a2ui" }
          }
        ]
      }
    }
  }
}
```

The payload uses the same `StreamResponse` format as SSE streaming — the client gets the same event types regardless of transport.

### 3. Client Acts on the Notification

When the client receives an `input-required` notification:

1. Parse the A2UI spec from the message parts
2. Present it to a human (or resolve programmatically)
3. Send the resolution back via `message/send` with the same `contextId`

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "kind": "text", "text": "{\"decision\": \"approve\"}" }],
      "contextId": "task-uuid-123"
    }
  }
}
```

***

## Managing Push Configs

Push notification configuration can also be managed separately from message sending:

### Set Config for an Existing Task

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tasks/pushNotificationConfig/set",
  "params": {
    "id": "task-uuid-123",
    "pushNotificationConfig": {
      "url": "https://my-system.example.com/a2a-callback",
      "token": "updated-token"
    }
  }
}
```

### Get Config for a Task

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tasks/pushNotificationConfig/get",
  "params": {
    "id": "task-uuid-123"
  }
}
```

These RPCs are available when the agent card advertises `capabilities.pushNotifications: true`.

***

## Security

Push notifications involve server-initiated outbound HTTP requests to client-provided URLs. Both sides have security responsibilities.

### Svantic (Sender)

* **URL validation.** Svantic validates push notification URLs before sending to them. This prevents SSRF attacks where a client tricks Svantic into making requests to internal services.
* **Authentication.** When `authentication` is provided, Svantic includes the specified credentials in the outbound request headers.
* **Token inclusion.** The `token` from the push config is sent in the `X-A2A-Notification-Token` header, allowing receivers to verify the notification matches an expected task.

### Client (Receiver)

* **Verify authenticity.** Check the `X-A2A-Notification-Token` header matches the token you provided when configuring the push notification.
* **Verify sender.** Validate the JWT signature if Svantic signs notifications with asymmetric keys (ECDSA/RSA via JWKS).
* **Reject stale.** Check timestamps in the notification to reject replay attacks.
* **Idempotency.** The same state transition may be delivered more than once (network retries). Handle duplicates gracefully.

***

## Comparison: Push Notifications vs Notification Channels

| Aspect            | A2A Push Notifications                          | Svantic Notification Channels                                       |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| **Purpose**       | Inform the calling system of task state changes | Alert humans when policies trigger                                  |
| **Configured by** | Caller, per task, at submission time            | Tenant admin, in dashboard Settings                                 |
| **Payload**       | A2A `StreamResponse` (protocol standard)        | Channel-native format (Block Kit, HTML, etc.)                       |
| **Audience**      | The system that submitted the task              | Humans or ops systems linked to the policy                          |
| **Channels**      | Single URL per task                             | Multiple: webhook, Slack, email                                     |
| **Bidirectional** | Via follow-up `message/send`                    | Slack: yes (interactive buttons). Email: no. Webhook: via callback. |
| **Standard**      | A2A v1.0.0 spec                                 | Svantic platform feature                                            |

Both mechanisms fire independently. A task that enters `input-required` triggers A2A push notifications (if configured) AND policy-linked notification channels (if configured). They serve different audiences and purposes.

***

## Agent Card

Agents advertise push notification support in their agent card:

```json theme={null}
{
  "name": "savant",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  }
}
```

When `pushNotifications` is `false`, the `tasks/pushNotificationConfig/set` and `/get` RPCs return `PushNotificationNotSupportedError`.

***

## Further Reading

* [Notifications](./notifications) — Svantic's policy-linked notification channels
* [Policies Guide](../guides/policies) — create and manage unified policies
* [Channels Guide](../guides/channels) — configure delivery endpoints
* [A2UI](./a2ui) — the structured payload format for human-interaction requests
* [Streaming & Events](./streaming) — SSE streaming for connected clients
* [A2A Protocol — Push Notifications](https://a2a-protocol.org/latest/topics/streaming-and-async/) — the full A2A specification