Documentation Index
Fetch the complete documentation index at: https://docs.getbindu.com/llms.txt
Use this file to discover all available pages before exploring further.
Push notification configurations define how servers send real-time updates to clients outside of active sessions. Bindu supports multiple notification patterns following the A2A Protocol specification.
PushNotificationConfig
Defined in bindu/common/protocol/types.py:397.
Schema (exact):
@pydantic.with_config(A2A_MODEL_CONFIG)
class PushNotificationConfig(TypedDict):
"""Configuration for push notifications.
When the server needs to notify the client of an update outside of a connected session.
"""
id: Required[UUID]
"""The ID of the push notification configuration."""
url: Required[str]
"""The URL of the push notification configuration."""
token: NotRequired[str]
"""The token of the push notification configuration."""
authentication: NotRequired[SecurityScheme]
"""The authentication of the push notification configuration."""
authentication field is a SecurityScheme — the same discriminated union used for inbound auth on the agent. This is a deliberate choice: the agent declares how it will authenticate to your webhook using the same vocabulary you’d use to declare how callers authenticate to it.
Use Case: Webhook with bearer-token auth (SecurityScheme form)
{
"id": "8f0b6df8-1f1e-4b2d-9b0a-6c5e7e4d3a2b",
"url": "https://client.example.com/webhook/notifications",
"token": "secure-webhook-token",
"authentication": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Server-issued JWT for this webhook audience"
}
}
{
"id": "8f0b6df8-1f1e-4b2d-9b0a-6c5e7e4d3a2b",
"url": "https://client.example.com/webhook/notifications",
"authentication": {
"type": "apiKey",
"name": "X-Webhook-Key",
"in": "header"
}
}
PushNotificationAuthenticationInfo
Defined in bindu/common/protocol/types.py:417.
This type exists in the schema as an A2A-spec-compatibility shape, but PushNotificationConfig.authentication is typed as SecurityScheme, not PushNotificationAuthenticationInfo. Use SecurityScheme when sending a config; treat this type as informational. @pydantic.with_config(A2A_MODEL_CONFIG)
class PushNotificationAuthenticationInfo(TypedDict):
"""Authentication information for push notifications."""
schemes: list[str]
"""A list of supported authentication schemes (e.g., 'Basic', 'Bearer')."""
credentials: NotRequired[str]
"""Optional credentials required by the push notification endpoint."""
TaskPushNotificationConfig
Defined in bindu/common/protocol/types.py:428.
Schema (exact):
@pydantic.with_config(A2A_MODEL_CONFIG)
class TaskPushNotificationConfig(TypedDict):
"""Configuration for task push notifications."""
id: Required[UUID]
"""The ID of the task push notification configuration."""
push_notification_config: Required[PushNotificationConfig]
"""The push notification configuration of the task push notification configuration."""
long_running: NotRequired[bool]
"""Flag indicating task expects to run longer than typical request timeouts.
When True, the push_notification_config should be persisted for notifications
across server restarts. Defaults to False if not specified.
"""
The top-level id here is the task ID that this notification config is bound to — not a separate config identifier. The field is id, not taskId.
{
"id": "43667960-d455-4453-b0cf-1bae4955270d",
"longRunning": true,
"pushNotificationConfig": {
"id": "8f0b6df8-1f1e-4b2d-9b0a-6c5e7e4d3a2b",
"url": "https://client.example.com/webhook/a2a-notifications",
"token": "secure-client-token-for-task-aaa",
"authentication": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
longRunning: true tells the server to persist the webhook configuration across restarts so notifications still fire when the task finally completes. Wired through the JSON-RPC methods tasks/pushNotificationConfig/{set,get,list,delete} (settings.py:445-448).
How Push Notifications Work
Workflow:
- Client configures push notifications when sending a message via
message/send
- Server acknowledges the task and begins processing
- Server completes the task and POSTs notification to the client’s webhook URL
- Client validates the notification using the token and authentication
- Client processes the task update (e.g., updates UI, notifies user)
Notification Delivery:
When a task state changes, the server sends an HTTP POST to the configured webhook URL:
POST /webhook/a2a-notifications HTTP/1.1
Host: client.example.com
Authorization: Bearer <server_jwt_for_webhook_audience>
Content-Type: application/json
X-A2A-Notification-Token: secure-client-token-for-task-aaa
{
"id": "43667960-d455-4453-b0cf-1bae4955270d",
"contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4",
"status": {
"state": "completed",
"timestamp": "2024-03-15T18:30:00Z"
},
"kind": "task"
}
Summary
Push notifications solve a simple problem: instead of constantly asking “Is it done yet?”, the agent calls you when it’s finished.
You configure a PushNotificationConfig with your webhook URL and token—like giving the agent your callback number. Add PushNotificationAuthenticationInfo to specify how the agent should authenticate when calling your webhook. Use TaskPushNotificationConfig to route different tasks to different endpoints with their own security requirements.
This eliminates polling overhead and enables real-time updates for long-running operations—report generation, batch processing, or workflows needing human confirmation.
