Skip to main content

​
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

ScenarioRecommended Approach
Short task, client waitingmessage/send (synchronous) — response comes in the same HTTP request
Interactive session, real-time updatesmessage/stream (SSE) — events streamed as they happen
Long-running task, client can hold connectionmessage/stream (SSE) — persistent connection with incremental updates
Long-running task, client disconnectsPush notifications — POST updates to callback URL
Fire-and-forget from serverless/mobilePush notifications — no persistent connection possible
External orchestrator submitting tasksPush 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"
        }
      }
    }
  }
}
FieldRequiredPurpose
urlYesHTTPS endpoint where Svantic will POST task updates
tokenNoOpaque token Svantic includes in the notification header — lets the receiver validate the notification belongs to the expected task
authenticationNoHow 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:
  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
{
  "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

AspectA2A Push NotificationsSvantic Notification Channels
PurposeInform the calling system of task state changesAlert humans when policies trigger
Configured byCaller, per task, at submission timeTenant admin, in dashboard Settings
PayloadA2A StreamResponse (protocol standard)Channel-native format (Block Kit, HTML, etc.)
AudienceThe system that submitted the taskHumans or ops systems linked to the policy
ChannelsSingle URL per taskMultiple: webhook, Slack, email
BidirectionalVia follow-up message/sendSlack: yes (interactive buttons). Email: no. Webhook: via callback.
StandardA2A v1.0.0 specSvantic 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.

​
Further Reading