Push Notifications

Push notifications allow agents to deliver task status updates to a webhook URL in real time — no polling required. This is especially useful for long-running or asynchronous tasks where the agent returns submitted immediately and processes the work in the background.

How It Works

The A2A protocol defines a push notification mechanism where:

1. The client includes a pushNotificationConfig when sending a message
2. The agent creates a webhook subscription for the task
3. As the task progresses, the agent POSTs status updates to the configured URL
4. The client receives updates without needing to poll tasks/get

Client                          Agent
  │                               │
  │── message/send ──────────────▶│  (includes pushNotificationConfig)
  │◀── "submitted" ──────────────│  (immediate response)
  │                               │
  │                               │  ... agent processes task ...
  │                               │
  │◀── POST webhook ─────────────│  (state: "working")
  │◀── POST webhook ─────────────│  (state: "completed" + result)

Configuring a Webhook

1. Open a project and go to the Test tab
2. Expand Advanced Settings below the message input
3. Under Push Notification (Webhook), enter your webhook URL
4. Optionally provide a Bearer Token for authentication
5. Send a message — the request will automatically switch to non-blocking mode

When a webhook is configured, a banner appears above the chat showing the active subscription. The message area also shows a notice that the task was submitted and results will be delivered to your webhook.

Tip: You can use services like webhook.site or RequestBin to quickly create a test endpoint for receiving webhooks.

Active Subscriptions

Once a message is sent with a webhook URL, a subscription is created for that task. Active subscriptions appear as a banner above the chat area:

• The banner shows each subscribed URL
• Click the x button to remove a subscription (this also clears the URL from Advanced Settings)
• If you have existing subscriptions, the webhook URL field shows a dropdown to select from them or enter a new URL

Webhook Payload

Each webhook delivery sends a JSON-RPC notification:

{
  "jsonrpc": "2.0",
  "method": "tasks/pushNotification",
  "params": {
    "taskId": "task-uuid",
    "status": {
      "state": "completed",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "message": { ... }
    }
  }
}

Authentication Headers

If you provide a bearer token, the webhook request includes:

Authorization: Bearer <your-token>

Subscriptions also support custom authentication schemes configured via the A2A protocol's authentication field.

Webhooks Tab

For mock agents, the project page includes a Webhooks tab that provides full observability into webhook activity:

Subscriptions

Lists all active webhook subscriptions for the current conversation's task, showing:

• URL — The webhook endpoint
• Task ID — Which task the subscription is for
• Created — When the subscription was registered

Delivery Log

Every webhook delivery is logged with:

Click any delivery row to expand it and see the full request and response bodies.

Managing Subscriptions via A2A

The A2A protocol also defines JSON-RPC methods for managing push notification subscriptions programmatically:

These are available on the mock agent's A2A endpoint (/api/mock-agents/:id/a2a).

Troubleshooting

Webhook not receiving deliveries

• Ensure the webhook URL is publicly accessible (localhost URLs won't work in production)
• Check the Webhooks tab delivery log for error details
• Verify any firewall or network rules allow incoming POST requests

Subscription created but no delivery

• Check that the agent's AgentCard has capabilities.pushNotifications: true
• Look at the delivery log for failed attempts with error messages
• Ensure your endpoint responds with a 2xx status code

Multiple deliveries for the same task

This is expected — the agent sends a webhook for each state transition (e.g., working → completed). Each delivery is logged separately.