Webhooks & Agent Info

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"

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 -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"
      }
    }
  }'

{
  "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"

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 -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": {}
  }'

{
  "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"

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 -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
    }
  }'

{
  "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

API Documentation

A2A Protocol Endpoints

Webhooks & Agent Info

Overview

tasks/pushNotificationConfig/set

Request Parameters

Response

Example

tasks/pushNotificationConfig/get

Request Parameters

Response

Example

agent/authenticatedExtendedCard

Request Parameters

Response

Example

Webhook Payload Format

Webhook Request Headers

Webhook Payload

Webhook Events

Webhook Security

Signature Verification

Best Practices

API Documentation

A2A Protocol Endpoints

​Overview

​tasks/pushNotificationConfig/set

​Request Parameters

​Response

​Example

​tasks/pushNotificationConfig/get

​Request Parameters

​Response

​Example

​agent/authenticatedExtendedCard

​Request Parameters

​Response

​Example

​Webhook Payload Format

​Webhook Request Headers

​Webhook Payload

​Webhook Events

​Webhook Security

​Signature Verification

​Best Practices

Overview

tasks/pushNotificationConfig/set

Request Parameters

Response

Example

tasks/pushNotificationConfig/get

Request Parameters

Response

Example

agent/authenticatedExtendedCard

Request Parameters

Response

Example

Webhook Payload Format

Webhook Request Headers

Webhook Payload

Webhook Events

Webhook Security

Signature Verification

Best Practices