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 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 |
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" }
}
]
}
}
}
}
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"
}
}
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 |
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
}
}
pushNotifications is false, the tasks/pushNotificationConfig/set and /get RPCs return PushNotificationNotSupportedError.
Further Reading
