Webhooks & Agent Info

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    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"
        },
        events: ["task.completed", "task.failed"],
        secret: "your-webhook-secret"
      }
    }
  })
});

const result = await response.json();
console.log(result);

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

POST

api

a2a

{agent_id}

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    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"
        },
        events: ["task.completed", "task.failed"],
        secret: "your-webhook-secret"
      }
    }
  })
});

const result = await response.json();
console.log(result);

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

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "tasks/pushNotificationConfig/set"

object

required

Webhook configuration parameters

Show params properties

object

required

Webhook configuration object

Show config properties

string

required

Webhook endpoint URL that will receive notifications

object

Optional HTTP headers to include in webhook requests

array

Array of events to subscribe to (default: all events)Options: ["task.submitted", "task.working", "task.completed", "task.failed", "task.canceled"]

object

Retry configuration for failed webhook deliveries

Show retryPolicy properties

number

Maximum number of retry attempts (default: 3)

number

Exponential backoff multiplier (default: 2.0)

number

Initial delay in seconds (default: 1)

string

Secret for webhook signature verification (HMAC-SHA256)

string

Optional: Configure webhooks for specific task only

Response

string

JSON-RPC version, always "2.0"

object

Configuration result

Show result properties

boolean

Whether webhook was successfully configured

string

Unique identifier for this webhook configuration

string

Configured webhook URL

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    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"
        },
        events: ["task.completed", "task.failed"],
        secret: "your-webhook-secret"
      }
    }
  })
});

const result = await response.json();
console.log(result);

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

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "tasks/pushNotificationConfig/get"

object

Optional parameters

Show params properties

string

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

Response

string

JSON-RPC version, always "2.0"

object

Current webhook configuration

Show result properties

object

Webhook configuration (null if not configured)

Show config properties

string

Configured webhook URL

array

Subscribed events

object

Retry configuration

string

Configuration creation timestamp

string

Last webhook delivery timestamp

string

Configuration identifier

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

{
  "jsonrpc": "2.0",
  "result": {
    "config": null,
    "configId": null,
    "active": false
  },
  "id": "req-get-webhook"
}

agent/authenticatedExtendedCard

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

Request Parameters

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "agent/authenticatedExtendedCard"

object

Optional parameters

Show params properties

boolean

Include detailed capability information (default: true)

boolean

Include usage metrics and statistics (default: false)

Response

string

JSON-RPC version, always "2.0"

object

Agent information

Show result properties

object

Agent details

Show agent properties

string

Agent unique identifier

string

Agent display name

string

Agent description

string

Agent version

string

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

string

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

object

Agent capabilities

Show capabilities properties

array

List of supported A2A methods

object

File upload capabilities

Show fileUpload properties

boolean

Whether file upload is supported

number

Maximum file size in bytes

array

Supported MIME types

boolean

Whether streaming is supported

boolean

Whether multi-turn conversations are supported

boolean

Whether webhook notifications are supported

object

Usage limits and quotas

Show limits properties

number

Rate limit for requests per minute

number

Maximum concurrent tasks

number

Maximum message length in characters

object

Usage metrics (if requested)

Show metrics properties

number

Total requests processed

number

Average response time in milliseconds

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "req-agent-info",
    method: "agent/authenticatedExtendedCard",
    params: {
      includeCapabilities: true,
      includeMetrics: false
    }
  })
});

const result = await response.json();
console.log(result);

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

​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