A2A push notifications

A2A push notifications (A2A v1.0 §6.3) replace the poll loop a federating peer would otherwise run against tasks/get. Register a callback URL on the task when you send it, and every lifecycle transition is POSTed to that URL the moment the executor advances the task. Use polling and push together, or either alone — the task ledger records everything regardless. The A2A federation reference covers the endpoints this guide builds on; this guide is the push-specific walkthrough.

1. The `pushNotifications` capability flag

Every AgentCard Orbit serves advertises its push capability under metadata.capabilities:

{
  "name": "Order Status Agent",
  "metadata": {
    "capabilities": {
      "streaming": false,
      "pushNotifications": true,
      "extendedAgentCard": false
    }
  }
}

Fetch the card before you subscribe — see Discovery modes for the card URL and access policy:

curl -s https://api.orbit.devotel.io/api/v1/agents/agent_abc/.well-known/agent-card.json?tenant=tenant_abc \
  | jq '.metadata.capabilities'

"pushNotifications": true means the agent accepts a registered pushNotification target on tasks/send (REST or JSON-RPC) and delivers lifecycle callbacks to it. A peer that never checks the flag can still attempt a subscription — Orbit validates the target at send time and rejects a malformed one with a 422 — but checking the flag first avoids wasted envelopes on peers that poll only. Attach a pushNotification block to the task-create request. The same block is accepted on both transports — the REST shorthand and the JSON-RPC tasks/send method — and on the dashboard’s outbound-delegation path. REST:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_abc/a2a/tasks?tenant=tenant_abc \
  -H "Content-Type: application/json" \
  -H "X-A2A-Signature: t=<unix_seconds>,v1=<hmac_hex>" \
  -d '{
    "skill": "order_status",
    "message": {
      "role": "user",
      "parts": [{ "kind": "text", "text": "Status of order ORD-89721" }]
    },
    "pushNotification": {
      "url": "https://you.example.com/a2a/callback",
      "token": "your-callback-bearer-token"
    }
  }'

JSON-RPC:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_abc/a2a?tenant=tenant_abc \
  -H "Content-Type: application/json" \
  -H "X-A2A-Signature: t=<unix_seconds>,v1=<hmac_hex>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "tasks/send",
    "params": {
      "skill": "order_status",
      "message": {
        "role": "user",
        "parts": [{ "kind": "text", "text": "Status of order ORD-89721" }]
      },
      "pushNotification": {
        "url": "https://you.example.com/a2a/callback",
        "token": "your-callback-bearer-token"
      }
    }
  }'

The pushNotification block has three fields:

Field	Required	Notes
`url`	yes	HTTPS only — plain `http:`, localhost, and private/link-local hosts are rejected at send time (422 / `INVALID_PARAMS`).
`token`	no	Bearer credential Orbit sends back as `Authorization: Bearer <token>` on every callback. Max 512 characters.
`headers`	no	Extra static headers merged into every callback POST (custom header names). Use instead of `token` when your endpoint wants a different scheme.

Subscribing from the dashboard instead of curl: open Agents → → A2A → Delegate to peer and fill the optional push-URL field — the drawer forwards the value as the same pushNotification block. Subscribing is per task. A long-lived integration registers the callback on each task it sends; there is no agent-level default target.

3. Webhook endpoint shape

Deliver your callback on any HTTPS endpoint you control. Orbit POSTs a JSON-RPC-shaped envelope:

POST /a2a/callback HTTP/1.1
Host: you.example.com
Content-Type: application/json
Authorization: Bearer your-callback-bearer-token
X-Orbit-A2A-Push-Signature: <detached Ed25519 JWS>

{
  "jsonrpc": "2.0",
  "method": "taskStateUpdate",
  "params": {
    "taskId": "agentA2aTask_9f4c…",
    "status": "completed",
    "output": { "…": "…" }
  }
}

Aspect	Behaviour
Trigger statuses	`completed`, `failed`, `cancelled`. Outbound delegations also push intermediate `working` flips driven by the peer’s own callbacks.
Payload	`params.taskId`, `params.status`, `params.output` when the task produced output, `params.error` when it failed.
Headers	`content-type: application/json`, plus your `token`/`headers` values verbatim, plus the signature header (next section).
Retries	None — delivery is best-effort by design, so the task lifecycle never hinges on your endpoint being up. A failed delivery is logged on the Orbit side; poll `tasks/get` after a silence window rather than waiting for a retry that won’t come.
Re-validation	The `url` is re-checked against the SSRF guard at every delivery, not only at send time. If a once-public URL has flipped to a private/link-local address, the delivery is skipped.

Answer 2xx. Any other response (or a connection failure) is recorded as a delivery failure on the task; the status transition itself still succeeds.

4. Verify the callback

Two signing schemes cover the callback; reject unsigned traffic at your endpoint either way. Detached Ed25519 JWS — X-Orbit-A2A-Push-Signature. When the Orbit deployment has its agent signing key provisioned, this header carries a compact JWS over the exact request body. Resolve the signing key from the JWKS URL the AgentCard advertises at metadata.a2aBearerAuth.jwksUri (also published on the Web Bot Auth directory endpoint) and verify with the kid in the JWS header. This is the preferred scheme: no shared secret crosses the integration. HMAC fallback — X-A2A-Signature. When no signing key is provisioned, Orbit falls back to the same shared-secret scheme used on inbound task calls: t=<unix_seconds>,v1=HMAC_SHA256(secret, "<t>.<raw_body>"). Verify with the A2A shared secret you already hold for that peer — see HMAC signing (task calls). For mTLS between your gateway and Orbit’s egress IPs, terminate it at your edge and still apply one of the two payload signatures — transport authentication and payload authentication answer different questions (who dialed vs. who signed this body).

5. Tear down a subscription

Subscriptions die with the task — there is no separate unsubscribe call to track.

Cancel the task (tasks/cancel, or REST PATCH …/a2a/tasks/{taskId} with { "status": "cancelled" }): the terminal transition is the last callback your URL receives.
Let the task finish: completed / failed are terminal too; no further callbacks fire afterwards.
Rotate away: if a registered callback URL must change mid-flight, finish/cancel the task and re-send it with the new target. The stored target on an existing task is never mutated.

6. Operator surface — seeing what’s subscribed

The dashboard lists every push target along with the task it belongs to:

Agents → → A2A → Task history — open a task row; the detail view shows the registered callback URL and whether the last delivery landed or was skipped.
API: GET /api/v1/agents/{agentId}/a2a/tasks/{taskId} returns the task envelope; the subscribed target sits under metadata.a2a_push.

Wire GET …/a2a/tasks (authenticated list endpoint) into your own operations dashboard if you need a fleet-level view of open subscriptions — the same payload shape applies.

Errors

Symptom	Cause
`422` / `INVALID_PARAMS` at subscribe time	`url` is not public HTTPS, or the block is malformed.
Callback never arrives	Delivery failure is only recorded on the Orbit side; check the task detail view, then fall back to `tasks/get`.
Callback arrives unsigned	No signing key provisioned on the Orbit side → HMAC fallback path. Verify the `X-A2A-Signature` header with your shared secret.
Stale callback URL after a task finished	Expected — subscriptions are per task and terminal.

Work through Troubleshooting: A2A federation for the wider federation failure taxonomy.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

A2A push notifications — subscribe to task lifecycle updates

A2A push notifications

1. The `pushNotifications` capability flag

3. Webhook endpoint shape

4. Verify the callback

5. Tear down a subscription

6. Operator surface — seeing what’s subscribed

Errors

See also

​A2A push notifications

​1. The pushNotifications capability flag

​2. Subscribe with pushNotification on tasks/send

​3. Webhook endpoint shape

​4. Verify the callback

​5. Tear down a subscription

​6. Operator surface — seeing what’s subscribed

​Errors

​See also

A2A push notifications

1. The `pushNotifications` capability flag

2. Subscribe with `pushNotification` on `tasks/send`

3. Webhook endpoint shape

4. Verify the callback

5. Tear down a subscription

6. Operator surface — seeing what’s subscribed

Errors

See also