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, 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:

{
  "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:

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:

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

{
  "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

{
  "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

{
  "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:

{
  "name": "savant",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  }
}

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

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

Push notifications

Push Notifications

When to Use Push Notifications

How It Works

1. Client Provides Push Config

2. Svantic POSTs State Changes

3. Client Acts on the Notification

Managing Push Configs

Set Config for an Existing Task

Get Config for a Task

Security

Svantic (Sender)

Client (Receiver)

Comparison: Push Notifications vs Notification Channels

Agent Card

Further Reading

​Push Notifications

​When to Use Push Notifications

​How It Works

​1. Client Provides Push Config

​2. Svantic POSTs State Changes

​3. Client Acts on the Notification

​Managing Push Configs

​Set Config for an Existing Task

​Get Config for a Task

​Security

​Svantic (Sender)

​Client (Receiver)

​Comparison: Push Notifications vs Notification Channels

​Agent Card

​Further Reading

Push Notifications

When to Use Push Notifications

How It Works

1. Client Provides Push Config

2. Svantic POSTs State Changes

3. Client Acts on the Notification

Managing Push Configs

Set Config for an Existing Task

Get Config for a Task

Security

Svantic (Sender)

Client (Receiver)

Comparison: Push Notifications vs Notification Channels

Agent Card

Further Reading