A2A Push Notifications
Purpose
This functional area lets a caller ask the platform to push task status updates to a webhook it controls,
instead of having to poll GetTask or hold a SendStreamingMessage connection open. It gives long-lived
callers (orchestrators, background integrations) a reliable, out-of-band way to learn when a task they
started reaches a new state.
Main Capabilities
- register a webhook target for a specific task (
CreateTaskPushNotificationConfig) - retrieve one previously registered config (
GetTaskPushNotificationConfig) - list every config registered for a task (
ListTaskPushNotificationConfigs) - remove a config (
DeleteTaskPushNotificationConfig) - view delivery history for a task's push notification configs from the Portal (admin, read-only)
How It Works
A caller registers a webhook — a URL, an optional authentication kind (bearer token, API key, or basic auth), and the id of a secret its own tenant already holds, which the platform resolves at delivery time, never the raw credential itself — against a specific task it already knows the id of. From that point on, every time the task's status changes, the platform posts a small notification (task id, new status, an optional status reason, and a timestamp) to that webhook.
This is entirely the calling agent's own choice, made through the protocol itself — there is no administrator-authored equivalent. An admin cannot create, edit, or delete a push notification config from the Portal; the A2A specification puts webhook configuration in the calling agent's hands, and this platform follows that model exactly, the same way it never invents an admin-facing override for what a caller chooses to send in a request body.
What triggers a delivery
A delivery attempt is triggered by exactly one thing: the task's recorded status actually changing (for
example, moving from submitted to completed, or to failed). Every active, non-deleted config
registered against that task receives its own attempt, independent of the others — one config failing
never affects delivery to another.
The guarantees that apply to every delivery
Push notification delivery reuses the same security posture this platform already applies to every other outbound webhook it operates (audit delivery targets, downstream API calls), rather than a lighter, special case for this one feature:
- The destination is always validated against the platform's outbound allowlist — not only when the config is first created, but immediately before every single delivery attempt, including retries. A host that was allowed when the config was created but has since been removed from the allowlist stops receiving deliveries the moment that happens, without anyone needing to touch the config itself.
- Credentials are never stored or logged in the clear. A config holds a reference to a secret, not the secret's value; the value is resolved only at the moment of sending, attached to the outbound request, and discarded — it is never written into any delivery-attempt record, so a failure detail can be inspected safely without exposing what the webhook's own credential was.
- A caller can only name a secret its own tenant already holds. The webhook credential is identified by the id of a secret registered to that tenant (or one the platform shares with every tenant), and that ownership is checked when the config is created and again at every delivery. A caller cannot name a secret belonging to another tenant, and cannot name one by guessing at a label — so this feature offers no route to reading a credential the caller was not already entitled to use. If the secret is later removed from the tenant, deliveries for that config fail rather than falling back to anything else, and the config has to be re-created against a secret that still exists.
- Retries are bounded by a total attempt budget, not stacked on top of a guaranteed first attempt. A transient failure (the target is briefly unreachable, returns a 5xx, or rate-limits the request) is retried on a backoff schedule up to that budget; a definitive failure (a bad URL rejected by the allowlist, or a 4xx response that isn't a rate limit) is never retried, because retrying it would not change the outcome.
- Every attempt is recorded, whether it succeeded, failed, or was rejected outright — this is what makes the delivery history described below possible, and it is what an operator would need to diagnose "why didn't my webhook fire" without having to reproduce the failure themselves.
Viewing Delivery History in the Portal
An administrator does not configure push notification webhooks, but can see what happened once they exist. Delivery history for a task's push notification configs is available as a read-only panel wherever that task already appears in the Portal's governance monitoring surfaces — specifically, within the Call Flow Dashboard's trace detail view, on the step that concerns that task (a task lookup, a cancellation, a subscription, or the config write itself). Opening that step shows every recorded delivery attempt: which attempt number it was, whether it was delivered, failed, or rejected, the HTTP status code returned (when a request was actually sent), and a short failure detail when relevant. This view is deliberately display-only, matching the caller-configures-its-own-webhook model described above — there is nothing to edit or retry from here.
Functional Value
This area lets an A2A caller build reliable, event-driven integrations against the platform without polling or holding a connection open, while keeping every outbound webhook this platform sends under the exact same SSRF, credential-custody, and retry-discipline guarantees every other outbound call already has — and gives an operator a way to see what actually happened to a delivery without needing direct access to the caller's own systems.