Webhooks & Agent Info

Configure push notifications and retrieve agent metadata for A2A integrations

Overview

These endpoints allow you to configure push notifications (webhooks) for asynchronous task updates and retrieve detailed agent information for better integration planning.

Push Notifications: Webhooks enable real-time notifications about task status changes, perfect for long-running operations where polling isn’t efficient.

---

tasks/pushNotificationConfig/set

Configure webhook endpoints to receive push notifications about task status changes.

Request Parameters

jsonrpc · string · required

JSON-RPC version, must be "2.0"

id · string · required

Unique identifier for this request

method · string · required

Must be "tasks/pushNotificationConfig/set"

params · object · required

Webhook configuration parameters

Show params properties

params.config · object · required

Webhook configuration object

Show config properties

params.config.url · string · required

Webhook endpoint URL that will receive notifications

params.config.headers · object

Optional HTTP headers to include in webhook requests

params.config.events · array

Array of events to subscribe to (default: all events)

Options: ["task.submitted", "task.working", "task.completed", "task.failed", "task.canceled"]

params.config.retryPolicy · object

Retry configuration for failed webhook deliveries

Show retryPolicy properties

params.config.retryPolicy.maxRetries · number

Maximum number of retry attempts (default: 3)

params.config.retryPolicy.backoffMultiplier · number

Exponential backoff multiplier (default: 2.0)

params.config.retryPolicy.initialDelay · number

Initial delay in seconds (default: 1)

params.config.secret · string

Secret for webhook signature verification (HMAC-SHA256)

params.taskId · string

Optional: Configure webhooks for specific task only

Response

jsonrpc · string

JSON-RPC version, always "2.0"

result · object

Configuration result

Show result properties

result.configured · boolean

Whether webhook was successfully configured

result.configId · string

Unique identifier for this webhook configuration

result.url · string

Configured webhook URL

result.events · array

List of subscribed events

Example

cURL

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-webhook-config",
    "method": "tasks/pushNotificationConfig/set",
    "params": {
      "config": {
        "url": "https://your-server.com/webhook/a2a",
        "headers": {
          "Authorization": "Bearer webhook-token",
          "X-Webhook-Source": "evo-ai"
        },
        "events": ["task.completed", "task.failed"],
        "retryPolicy": {
          "maxRetries": 5,
          "backoffMultiplier": 2.0,
          "initialDelay": 2
        },
        "secret": "your-webhook-secret"
      }
    }
  }'

Success

{
  "jsonrpc": "2.0",
  "result": {
    "configured": true,
    "configId": "webhook-config-123",
    "url": "https://your-server.com/webhook/a2a",
    "events": ["task.completed", "task.failed"]
  },
  "id": "req-webhook-config"
}

---

tasks/pushNotificationConfig/get

Retrieve current webhook configuration for the agent.

Request Parameters

jsonrpc · string · required

JSON-RPC version, must be "2.0"

id · string · required

Unique identifier for this request

method · string · required

Must be "tasks/pushNotificationConfig/get"

params · object

Optional parameters

Show params properties

params.taskId · string

Get configuration for specific task (if task-specific config exists)

Response

jsonrpc · string

JSON-RPC version, always "2.0"

result · object

Current webhook configuration

Show result properties

result.config · object

Webhook configuration (null if not configured)

Show config properties

result.config.url · string

Configured webhook URL

result.config.events · array

Subscribed events

result.config.retryPolicy · object

Retry configuration

result.config.createdAt · string

Configuration creation timestamp

result.config.lastUsed · string

Last webhook delivery timestamp

result.configId · string

Configuration identifier

result.active · boolean

Whether webhook is currently active

Example

cURL

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-get-webhook",
    "method": "tasks/pushNotificationConfig/get",
    "params": {}
  }'

Configured

{
  "jsonrpc": "2.0",
  "result": {
    "config": {
      "url": "https://your-server.com/webhook/a2a",
      "events": ["task.completed", "task.failed"],
      "retryPolicy": {
        "maxRetries": 5,
        "backoffMultiplier": 2.0,
        "initialDelay": 2
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsed": "2024-01-15T11:45:30Z"
    },
    "configId": "webhook-config-123",
    "active": true
  },
  "id": "req-get-webhook"
}

---

agent/authenticatedExtendedCard

Get detailed information about the agent, including capabilities, supported features, and metadata.

Request Parameters

jsonrpc · string · required

JSON-RPC version, must be "2.0"

id · string · required

Unique identifier for this request

method · string · required

Must be "agent/authenticatedExtendedCard"

params · object

Optional parameters

Show params properties

params.includeCapabilities · boolean

Include detailed capability information (default: true)

params.includeMetrics · boolean

Include usage metrics and statistics (default: false)

Response

jsonrpc · string

JSON-RPC version, always "2.0"

result · object

Agent information

Show result properties

result.agent · object

Agent details

Show agent properties

result.agent.id · string

Agent unique identifier

result.agent.name · string

Agent display name

result.agent.description · string

Agent description

result.agent.version · string

Agent version

result.agent.type · string

Agent type (e.g., “llm”, “workflow”, “sequential”)

result.agent.status · string

Current agent status (“active”, “inactive”, “maintenance”)

result.capabilities · object

Agent capabilities

Show capabilities properties

result.capabilities.supportedMethods · array

List of supported A2A methods

result.capabilities.fileUpload · object

File upload capabilities

Show fileUpload properties

result.capabilities.fileUpload.supported · boolean

Whether file upload is supported

result.capabilities.fileUpload.maxFileSize · number

Maximum file size in bytes

result.capabilities.fileUpload.supportedTypes · array

Supported MIME types

result.capabilities.streaming · boolean

Whether streaming is supported

result.capabilities.multiTurn · boolean

Whether multi-turn conversations are supported

result.capabilities.webhooks · boolean

Whether webhook notifications are supported

result.limits · object

Usage limits and quotas

Show limits properties

result.limits.requestsPerMinute · number

Rate limit for requests per minute

result.limits.concurrentTasks · number

Maximum concurrent tasks

result.limits.maxMessageLength · number

Maximum message length in characters

result.metrics · object

Usage metrics (if requested)

Show metrics properties

result.metrics.totalRequests · number

Total requests processed

result.metrics.averageResponseTime · number

Average response time in milliseconds

result.metrics.successRate · number

Success rate percentage

Example

cURL

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-agent-info",
    "method": "agent/authenticatedExtendedCard",
    "params": {
      "includeCapabilities": true,
      "includeMetrics": true
    }
  }'

Agent Information

{
  "jsonrpc": "2.0",
  "result": {
    "agent": {
      "id": "my-agent",
      "name": "Customer Support Assistant",
      "description": "AI agent specialized in customer support and FAQ responses",
      "version": "1.2.0",
      "type": "llm",
      "status": "active"
    },
    "capabilities": {
      "supportedMethods": [
        "message/send",
        "message/stream",
        "tasks/get",
        "tasks/cancel",
        "tasks/pushNotificationConfig/set",
        "tasks/pushNotificationConfig/get",
        "agent/authenticatedExtendedCard"
      ],
      "fileUpload": {
        "supported": true,
        "maxFileSize": 5242880,
        "supportedTypes": [
          "text/plain",
          "application/pdf",
          "image/jpeg",
          "image/png"
        ]
      },
      "streaming": true,
      "multiTurn": true,
      "webhooks": true
    },
    "limits": {
      "requestsPerMinute": 100,
      "concurrentTasks": 10,
      "maxMessageLength": 10000
    },
    "metrics": {
      "totalRequests": 15420,
      "averageResponseTime": 850,
      "successRate": 98.5
    }
  },
  "id": "req-agent-info"
}

---

Webhook Payload Format

When webhooks are configured, your endpoint will receive POST requests with the following payload structure:

Webhook Request Headers

Content-Type: application/json
X-Webhook-Event: task.completed
X-Webhook-Signature: sha256=<hmac-signature>
X-Webhook-Delivery: <delivery-id>
User-Agent: EvoAI-Webhook/1.0

Webhook Payload

{
  "event": "task.completed",
  "timestamp": "2024-01-15T10:32:15Z",
  "agentId": "my-agent",
  "taskId": "task-123",
  "data": {
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "Task completed successfully"
          }
        ]
      }
    },
    "contextId": "ctx-abc123",
    "duration": 125000,
    "completedAt": "2024-01-15T10:32:15Z"
  },
  "delivery": {
    "attempt": 1,
    "maxAttempts": 5
  }
}

Webhook Events

task.submitted

Sent when a task is submitted and queued for processing.

Data includes: taskId, submittedAt, estimatedDuration

task.working

Sent when a task starts processing (optional, based on agent implementation).

Data includes: taskId, startedAt, progress

task.completed

Sent when a task completes successfully.

Data includes: taskId, status.message, contextId, duration, completedAt

task.failed

Sent when a task fails during processing.

Data includes: taskId, status.error, duration, failedAt

task.canceled

Sent when a task is canceled.

Data includes: taskId, reason, canceledAt

Webhook Security

Signature Verification

If you provide a secret in your webhook configuration, each webhook request will include an HMAC-SHA256 signature:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

// Usage
const isValid = verifyWebhookSignature(
  JSON.stringify(webhookPayload),
  request.headers['x-webhook-signature'],
  'your-webhook-secret'
);

Best Practices

Security

• Always verify signatures when using webhook secrets
• Use HTTPS endpoints for webhook URLs
• Validate payload structure before processing
• Implement idempotency using delivery IDs

Performance

• Respond quickly (< 5 seconds) to avoid retries
• Process asynchronously for complex operations
• Return 2xx status codes for successful processing

Reliability

• Handle duplicate deliveries gracefully
• Implement proper error handling for webhook processing
• Monitor webhook delivery success rates