Webhooks & Agent Info

Configure push notifications and retrieve agent metadata for A2A integrations

POST /api/v1/a2a/{agent_id}

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

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