Key Features

• 🔄 Automatic Tracking: All agent activities, skill usage, and user actions are automatically tracked
• 📦 Performance Optimized: Non-blocking, batch-processed analytics with rate limiting
• 🛡️ Privacy Friendly: Only tracks important business events, not every interaction
• 📊 Rich Insights: Detailed analytics dashboard for admins and users
• 🔗 Platform Integration: Centralized analytics across all deployed agents

Using Analytics in Your Code

The analytics service is automatically available in all skills. You can also track custom events:

import { trackEvent, trackSkillUsage, trackApiCall } from '@agentdao/core';

// Track skill usage
await trackSkillUsage('WebSearchSkill', 'my-agent-123', {
  query: 'AI trends 2024',
  provider: 'google'
});

// Track API calls
await trackApiCall('web_search', true, 1500, {
  skill: 'WebSearchSkill',
  resultCount: 10
});

// Track custom events
await trackEvent({
  event_type: 'user_action',
  event_name: 'button_click',
  metadata: { button: 'submit', page: 'dashboard' }
});

Analytics Dashboard

Access your analytics data through the platform dashboard:

• User Analytics: Track user signups, logins, and activity patterns
• Agent Analytics: Monitor agent creation, deployment, and usage
• Skill Analytics: Track skill usage, performance, and error rates
• Challenge Analytics: Monitor challenge submissions and awards
• Admin Analytics: Comprehensive admin dashboard with system health metrics

Analytics API Endpoints

Access analytics data programmatically:

# Get analytics data
GET /api/dashboard/analytics?timeRange=30d&realTime=true

# Track an event
POST /api/analytics/track
{
  "event_type": "user_action",
  "event_name": "user_signup",
  "metadata": { "source": "github" }
}

# Batch analytics (for npm package)
POST /api/analytics/batch
{
  "events": [
    {
      "event_type": "skill_usage",
      "event_name": "skill_used",
      "skill_name": "WebSearchSkill",
      "metadata": { "query": "test" }
    }
  ]
}

Performance & Privacy

The analytics system is designed to be lightweight and privacy-friendly:

• Automatic Cleanup: Old data is automatically deleted after 90 days
• Rate Limiting: Maximum 10 events per user per minute

Real Agent Execution

Unlike mock implementations, AgentDAO now actually executes your agent code:

• Code Execution: Your agent code runs in a secure sandboxed environment
• Real Input/Output: Agents process actual user input and return real results
• Execution Logging: All executions are logged with timing and metadata
• Error Handling: Proper error capture and reporting
• Performance Tracking: Execution time and success rate monitoring

Test Agent Endpoint

The test endpoint now actually executes your agent with test input:

POST /api/dashboard/test-agent
Content-Type: application/json

{
  "projectId": "YOUR_PROJECT_ID",
  "testInput": "Hello, this is a test input"
}

Response:

{
  "success": true,
  "message": "Agent test completed successfully",
  "output": { "message": "Hello, this is a test input" },
  "executionTime": 125,
  "testInput": "Hello, this is a test input"
}

Run Agent Endpoint

The run endpoint executes your agent and streams real-time results:

POST /api/dashboard/run-agent
Content-Type: application/json

{
  "projectId": "YOUR_PROJECT_ID",
  "input": "User input here"
}

Streaming Response:

{"type": "log", "content": "Starting agent execution..."}
{"type": "log", "content": "Executing agent code..."}
{"type": "output", "content": "{\"result\": \"Agent response\"}"}
{"type": "log", "content": "Execution completed successfully in 150ms."}

Agent Code Requirements

Your agent code should follow these patterns:

// Option 1: Export a main function
async function main(input, config) {
  // Your agent logic here
  return { message: "Hello from agent!", input };
}

// Option 2: Export a handler function
async function handler(input, config) {
  // Your agent logic here
  return { message: "Hello from agent!", input };
}

// Option 3: Direct execution
// Your agent logic here
// The result will be automatically returned

ServiceBot MVP Flow

Create a complete monetization strategy using ServiceBot and AgentDAO:

1. User Registration: Users register via ServiceBot agent with email and domain
2. Domain Analysis: AgentDAO analyzes the domain using core skills
3. Web3 Payment: Users pay via Web3 integration with AgentDAO API
4. Email Confirmation: Payment confirmation sent via email
5. Dashboard Access: Users get access to manage their domains
6. Agent Configuration: Configure chat agents for each domain
7. Integration Options: JavaScript embed or API integration

Implementation Steps

Here's how to implement the ServiceBot integration:

// 1. Create ServiceBot Agent
const servicebotAgent = {
  name: "AgentDAO Registration Agent",
  skills: ["domain_analysis", "payment_processing", "email_notifications"],
  webhook_endpoints: ["/register", "/analyze", "/payment"]
};

// 2. Domain Analysis Service
const domainAnalysis = {
  endpoint: "/api/domain-analysis",
  skills: ["web_search", "content_analysis", "business_classification"]
};

// 3. Payment Integration
const paymentIntegration = {
  provider: "AgentDAO API",
  endpoint: "/api/agents/{agentId}/pricing-config",
  web3_support: true
};

// 4. Email Service
const emailService = {
  provider: "AgentDAO Email Service",
  templates: ["payment_confirmation", "welcome", "setup_guide"]
};

API Integration

Use the AgentPricingSDK to integrate with AgentDAO:

import { AgentPricingSDK } from '@agentdao/core';

// Initialize SDK
const pricingSDK = new AgentPricingSDK(agentId, {
  baseUrl: 'https://developers.agentdao.com',
  apiKey: 'your_api_key'
});

// Get pricing configuration
const config = await pricingSDK.getPricingConfig();

// Process payment
const payment = await pricingSDK.processPayment({
  plan: 'premium',
  amount: 100,
  token: 'ADAO',
  userWallet: '0x...'
});

// Send confirmation email
await pricingSDK.sendEmail({
  template: 'payment_confirmation',
  to: userEmail,
  data: { payment, domain }
});

Domain Management Dashboard

Create a simple dashboard for users to manage their domains:

// Dashboard API endpoints
GET /api/user/domains          // List user domains
POST /api/user/domains         // Add new domain
PUT /api/user/domains/:id      // Update domain config
DELETE /api/user/domains/:id   // Remove domain

// Domain configuration
{
  id: "domain_id",
  domain: "example.com",
  status: "active",
  payment_status: "paid",
  agent_config: {
    enabled: true,
    chat_widget: true,
    api_integration: false
  },
  analytics: {
    visitors: 1500,
    interactions: 250,
    revenue: 100
  }
}

Integration Options

Users can integrate the chat agent in two ways:

<script src="https://developers.agentdao.com/embed.js"></script>
<script>
  AgentDAO.init({
    agentId: 'your_agent_id',
    domain: 'your_domain.com',
    position: 'bottom-right'
  });
</script>

const response = await fetch('/api/agents/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'your_agent_id',
    message: userMessage,
    context: { domain: 'your_domain.com' }
  })
});

Installation

npm install @agentdao/core
# or
yarn add @agentdao/core

Basic Usage

import { AgentPricingSDK } from '@agentdao/core';

// Initialize SDK
const pricingSDK = new AgentPricingSDK(agentId, {
  baseUrl: 'https://developers.agentdao.com',
  apiKey: 'your_api_key'
});

// Get complete pricing configuration
const config = await pricingSDK.getPricingConfig();
console.log('Pricing Plans:', config.pricing.pricing_plans);
console.log('Accepted Tokens:', config.pricing.accepted_tokens);

Available Methods

Advanced Usage

// Check if agent has specific feature
const hasWeb3 = await pricingSDK.hasFeature('web3-subscription');
if (hasWeb3) {
  console.log('Agent supports Web3 subscriptions');
}

// Validate user access
const access = await pricingSDK.validateAccess(userId, token);
if (access.valid) {
  console.log('User has access to this agent');
}

// Get specific pricing plan
const plans = await pricingSDK.getPricingPlans();
const premiumPlan = plans.premium;
console.log('Premium plan:', premiumPlan);

// Check accepted tokens
const tokens = await pricingSDK.getAcceptedTokens();
if (tokens.ADAO) {
  console.log('Agent accepts ADAO tokens');
}

Error Handling

try {
  const config = await pricingSDK.getPricingConfig();
  console.log('Config loaded:', config);
} catch (error) {
  if (error.message.includes('Agent not found')) {
    console.error('Agent does not exist');
  } else if (error.message.includes('Access denied')) {
    console.error('API key does not have access to this agent');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Factory Function

import { createAgentPricingSDK } from '@agentdao/core';

// Create SDK using factory function
const pricingSDK = createAgentPricingSDK(agentId, {
  baseUrl: 'https://developers.agentdao.com',
  apiKey: 'your_api_key'
});

// Use the same way as constructor
const config = await pricingSDK.getPricingConfig();

Agent Logs

Get real-time logs of your agent executions:

GET /api/agent-logs

Response:

[
  {
    "time": "2:30:45 PM",
    "type": "success",
    "message": "Agent executed successfully",
    "agentName": "My Agent"
  },
  {
    "time": "2:30:40 PM", 
    "type": "error",
    "message": "Agent execution failed",
    "agentName": "My Agent"
  }
]

Agent Metrics

Get performance metrics for your agents:

GET /api/agent-metrics

Response:

[
  {
    "label": "Total Agents",
    "value": "5",
    "change": "+5"
  },
  {
    "label": "Deployed Agents", 
    "value": "3",
    "change": "+3"
  },
  {
    "label": "Active Agents",
    "value": "2", 
    "change": "+2"
  },
  {
    "label": "Total Executions",
    "value": "150",
    "change": "+150"
  },
  {
    "label": "Avg Execution Time",
    "value": "125.50ms",
    "change": "+125.50ms"
  },
  {
    "label": "Success Rate",
    "value": "98.5%",
    "change": "N/A"
  }
]

Creating Logs

You can also create custom logs for your agents:

POST /api/agent-logs
Content-Type: application/json

{
  "agentId": "YOUR_AGENT_ID",
  "logType": "info",
  "message": "Custom log message"
}

Log Types

• info: General information messages
• success: Successful operations
• warning: Warning messages
• error: Error messages

Agent Development

• Test Thoroughly: Use the real test endpoint to validate your agent logic before deployment
• Handle Errors: Implement proper error handling in your agent code
• Optimize Performance: Monitor execution times and optimize slow operations
• Use Environment Variables: Store sensitive data like API keys in environment variables
• Follow Security Best Practices: Never expose sensitive data in your agent responses

Monitoring & Logging

• Monitor Logs: Regularly check agent logs for errors and performance issues
• Track Metrics: Use the metrics endpoint to monitor agent performance over time
• Set Up Alerts: Create alerts for high error rates or slow execution times
• Log Important Events: Use custom logging for important agent events

API Usage

• Keep API Keys Secure: Never expose them in public code or client-side applications
• Follow Rate Limits: Implement exponential backoff for rate-limited requests
• Handle Errors Gracefully: Implement proper error handling for all API calls
• Use Streaming: Use the streaming run-agent endpoint for real-time responses

General Questions

• How do I get an API key?
  Create and manage API keys in your dashboard under API Management.
• Can I use the API without coding?
  Yes! Use the No-Code Agent Builder in your dashboard.
• Where can I find more examples?
  See the API Reference for more code samples.
• How do I get support?
  See below for support options.

Agent Execution

• Is agent execution real or simulated?
  AgentDAO now provides real agent execution. Your code actually runs in a sandboxed environment.
• How do I test my agent?
  Use the /api/dashboard/test-agent endpoint with your project ID and test input.
• How do I run my agent?
  Use the /api/dashboard/run-agent endpoint for real-time execution with streaming results.
• What programming languages are supported?
  Currently JavaScript/Node.js is supported for agent execution.

Monitoring & Logs

• How do I view agent logs?
  Use the /api/agent-logs endpoint to get execution logs.
• How do I get performance metrics?
  Use the /api/agent-metrics endpoint for detailed metrics.
• Can I create custom logs?
  Yes, use POST /api/agent-logs to create custom log entries.
• What log types are available?
  info, success, warning, and error log types are supported.

Common Error Types

• AuthenticationError - Invalid or expired API key
• RateLimitError - Too many requests
• ValidationError - Invalid request parameters
• TimeoutError - Request timed out

Error Handling Example

try {
  const response = await agent.execute({
    input: userInput,
    options: {
      timeout: 5000,
      retries: 3
    }
  });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    // Handle timeout
  } else if (error.code === 'RATE_LIMIT') {
    // Handle rate limit
  } else {
    // Handle other errors
  }
}

Key Features

• Multi-Agent Orchestration - Coordinate multiple agents to work together on complex tasks
• State Management - Maintain and share state between agents
• Event System - Handle asynchronous events and agent communication
• Data Pipeline - Process and transform data between agents
• Error Recovery - Automatic retry and fallback mechanisms

Basic Setup

import { AgentBridge } from '@agentdao/bridge';

const bridge = new AgentBridge({
  agents: {
    assistant: new AssistantAgent(),
    researcher: new ResearchAgent(),
    writer: new WriterAgent()
  },
  config: {
    maxRetries: 3,
    timeout: 30000
  }
});

Agent Communication

// Define a workflow
bridge.defineWorkflow('research-and-write', async (context) => {
  // Research phase
  const research = await context.agents.researcher.execute({
    query: context.input.topic
  });

  // Writing phase
  const article = await context.agents.writer.execute({
    content: research.data,
    format: 'blog-post'
  });

  return article;
});

// Execute the workflow
const result = await bridge.executeWorkflow('research-and-write', {
  topic: 'AI Ethics'
});

State Management

// Set state
bridge.setState('user-preferences', {
  language: 'en',
  tone: 'professional'
});

// Get state
const preferences = bridge.getState('user-preferences');

// Subscribe to state changes
bridge.subscribe('user-preferences', (newState) => {
  console.log('Preferences updated:', newState);
});

Event Handling

// Register event handlers
bridge.on('agent:error', async (error) => {
  console.error('Agent error:', error);
  await notifyAdmin(error);
});

bridge.on('workflow:complete', (result) => {
  console.log('Workflow completed:', result);
});

// Emit events
bridge.emit('custom:event', {
  type: 'notification',
  message: 'Task completed'
});

Data Pipeline

// Define data transformations
bridge.defineTransform('clean-text', (text) => {
  return text.trim().toLowerCase();
});

bridge.defineTransform('format-json', (data) => {
  return JSON.stringify(data, null, 2);
});

// Use in workflow
bridge.defineWorkflow('process-data', async (context) => {
  const rawData = await context.agents.collector.getData();
  const cleaned = await context.transform('clean-text', rawData);
  const formatted = await context.transform('format-json', cleaned);
  return formatted;
});

Error Recovery

// Configure retry strategy
bridge.configureRetry({
  maxAttempts: 3,
  backoff: 'exponential',
  maxDelay: 5000
});

// Define fallback behavior
bridge.defineFallback('research-agent', async (error) => {
  if (error.code === 'TIMEOUT') {
    return await context.agents.backupResearcher.execute(context.input);
  }
  throw error;
});

🚀 Quick Start

Get started with pricing integration in your deployed agent:

import { AgentPricingSDK } from '@agentdao/core';

// Initialize with your agent ID
const agentId = 123; // Replace with your actual agent ID
const pricingSDK = new AgentPricingSDK(agentId);

// Fetch pricing configuration
const config = await pricingSDK.getPricingConfig();
console.log('Pricing plans:', config.pricing.pricing_plans);

🔑 Key Features

• Centralized Pricing: Configure pricing plans in AgentDAO platform, use them in deployed agents
• Real-time Updates: Pricing changes are immediately available to deployed agents
• Access Control: Built-in validation for user plans and tokens
• Usage Limits: Enforce monthly requests, rate limiting, and feature restrictions
• Payment Integration: Calculate platform fees and developer revenue automatically
• Multi-token Support: Accept ADAO, ETH, USDC, and other tokens

📋 API Endpoints

Access pricing configuration via REST API:

GET /api/agents/{agentId}/pricing-config

Returns complete pricing configuration including plans, tokens, limits, and features.

Get agent info (claimed URL and API key):

GET /api/dashboard/agent-info?agentId={agentId}

Returns the claimed URL from agent submissions and the matching API key for the domain.

💳 Access Control Example

Implement access control in your deployed agent:

// Check if user has access
const accessResult = await pricingSDK.validateAccess('monthly', 'ADAO');

if (accessResult.hasAccess) {
  console.log('User has access to the agent');
  // Proceed with agent functionality
} else {
  console.log('Access denied:', accessResult.reason);
  // Redirect to pricing page or show upgrade message
}

📊 Usage Limits Example

Enforce usage limits based on your configuration:

// Check usage limits
const usageLimits = await pricingSDK.getUsageLimits();
const rateLimits = await pricingSDK.getRateLimits();

// Check against your database
const userUsage = await getUserUsageFromDatabase(userId);

if (usageLimits.requests_per_month && userUsage.requests >= usageLimits.requests_per_month) {
  throw new Error('Monthly request limit exceeded');
}

if (rateLimits.requests_per_minute && userUsage.recentRequests >= rateLimits.requests_per_minute) {
  throw new Error('Rate limit exceeded');
}

🎯 Feature-Based Access

Enable/disable features based on plan tiers:

// Check if specific features are enabled
const hasAnalytics = await pricingSDK.hasFeature('analytics');
const hasPrioritySupport = await pricingSDK.hasFeature('priority_support');

if (hasAnalytics) {
  enableAnalytics();
}

if (hasPrioritySupport) {
  enablePrioritySupport();
}

💰 Payment Processing

Process payments using your configured pricing:

// Process payment
const config = await pricingSDK.getPricingConfig();
const plans = await pricingSDK.getPricingPlans();
const tokens = await pricingSDK.getAcceptedTokens();

const plan = plans[userPlan];
const token = tokens[userToken];

const planPrice = plan.price;
const platformFee = config.pricing.platform_commission_rate / 100;
const platformAmount = planPrice * platformFee;
const developerAmount = planPrice - platformAmount;

// Process payment with your payment system
const paymentResult = await yourPaymentSystem.process({
  amount: planPrice,
  token: userToken,
  tokenAddress: token.address,
  platformAmount,
  developerAmount,
  developerWallet: config.pricing.payment_wallet_address
});

🔧 Express.js Middleware

Use middleware for automatic access control:

function createAccessControlMiddleware(agentId) {
  return async (req, res, next) => {
    const userPlan = req.headers['x-user-plan'];
    const userToken = req.headers['x-user-token'];
    
    const pricingSDK = new AgentPricingSDK(agentId);
    const accessResult = await pricingSDK.validateAccess(userPlan, userToken);
    
    if (!accessResult.hasAccess) {
      return res.status(403).json({
        error: 'Access denied',
        reason: accessResult.reason,
        requiredPlan: accessResult.requiredPlan
      });
    }
    
    req.pricingConfig = await pricingSDK.getPricingConfig();
    next();
  };
}

// Use middleware
app.use(createAccessControlMiddleware(123));

🔑 Getting Your API Key

To get the correct API key for your claimed domain:

1. Submit your agent to a URL in the marketplace
2. Once approved, your agent gets a claimed URL (e.g., "servicebot.com")
3. Create an API key with the same domain as your claimed URL
4. Use the agent-info endpoint to get the matching API key

// Get your agent's claimed URL and API key
const response = await fetch('/api/dashboard/agent-info?agentId=15');
const data = await response.json();

console.log('Claimed URL:', data.claimedUrl); // "servicebot.com"
console.log('API Key:', data.apiKey.key); // "ak_9zrytvahq8w0ldud4cu4dv"

// Use this API key for pricing configuration calls
const pricingSDK = new AgentPricingSDK(15, data.apiKey.key);

📖 Configuration in AgentDAO

Before using pricing integration, configure your agent in the AgentDAO platform:

1. Go to your agent in the Agent Builder
2. Set your payment wallet address
3. Enable "Available for Hire"
4. Add pricing plans (monthly, quarterly, annually, one-time)
5. Configure accepted tokens (ADAO, ETH, USDC, etc.)
6. Set usage limits and rate limits
7. Enable features for different plan tiers

📚 Additional Resources

• Complete Integration Guide
• Advanced Examples
• Simple Integration Examples
• Agent Info Endpoint Guide
• API Reference

Free Tier

• 100 requests per minute
• 1,000 requests per hour
• 10,000 requests per day

Pro Tier

• 1,000 requests per minute
• 10,000 requests per hour
• 100,000 requests per day

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600

Version Policy

• Major versions (v1, v2) are released every 6 months
• Minor updates are backward compatible
• Deprecated versions are supported for 12 months
• Breaking changes are only introduced in major versions

Version Headers

You can specify the API version in your requests:

Accept: application/vnd.agentdao.v1+json

Migration Guide

When upgrading to a new major version:

1. Review the changelog for breaking changes
2. Update your API calls to use the new version
3. Test your integration thoroughly
4. Monitor for any deprecation warnings

Real Agent Testing

AgentDAO now provides real agent testing capabilities. Your agents are actually executed during testing:

// Test your agent with real execution
const response = await fetch('/api/dashboard/test-agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    projectId: 'YOUR_PROJECT_ID',
    testInput: 'Hello, world!'
  })
});

const result = await response.json();
console.log(result);
// {
//   "success": true,
//   "message": "Agent test completed successfully",
//   "output": { "message": "Hello, world!" },
//   "executionTime": 125,
//   "testInput": "Hello, world!"
// }

Integration Testing

// Test agent with different inputs
const testCases = [
  { input: 'Hello', expected: /greeting/i },
  { input: 'Help', expected: /assist/i },
  { input: 'Error test', expected: /error/i }
];

for (const testCase of testCases) {
  const response = await fetch('/api/dashboard/test-agent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      projectId: 'YOUR_PROJECT_ID',
      testInput: testCase.input
    })
  });
  
  const result = await response.json();
  expect(result.success).toBe(true);
  expect(result.output).toMatch(testCase.expected);
}

Performance Testing

// Test agent performance
const startTime = Date.now();
const response = await fetch('/api/dashboard/test-agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    projectId: 'YOUR_PROJECT_ID',
    testInput: 'Performance test input'
  })
});

const result = await response.json();
const totalTime = Date.now() - startTime;

console.log('Total time:', totalTime, 'ms');
console.log('Execution time:', result.executionTime, 'ms');
console.log('Success:', result.success);

Error Testing

// Test error handling
try {
  const response = await fetch('/api/dashboard/test-agent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      projectId: 'INVALID_PROJECT_ID',
      testInput: 'Test input'
    })
  });
  
  const result = await response.json();
  expect(result.success).toBe(false);
  expect(result.error).toBeDefined();
} catch (error) {
  console.error('Test error:', error);
}

Common Issues

• Authentication Failed - Check your API key and ensure it's properly set in your environment variables.
• Rate Limit Exceeded - Implement exponential backoff and retry logic in your application.
• Timeout Errors - Increase the timeout value or optimize your agent's response time.
• Integration Issues - Verify your webhook URLs and ensure they're accessible.

Getting Started

1. Sign up for an account at developers.agentdao.com
2. Install the AgentDAO GitHub App for your account
3. Create a new agent from the dashboard
4. Choose a template or start from scratch
5. Deploy your agent with one click

Required Setup

• GitHub Account - Required for agent deployment
• API Keys - Depending on your agent's features:
  • OpenAI API Key for AI features
  • OpenWeather API Key for weather features
  • Other service-specific API keys as needed

Available Templates

• AI Chatbot
• Web Scraper Agent
• Data Analysis Agent
• SEO Analyzer
• Content Summarizer
• Customer Support Bot
• RSS News Summarizer
• Weather Reporter

How Webhooks Work

1. You create a webhook in your AgentDAO dashboard
2. AgentDAO sends HTTP POST requests to your webhook URL when events occur
3. Your service processes the webhook data and takes action
4. AgentDAO logs delivery attempts and handles retries

Key Features

• Real-time Notifications - Get instant updates when agents are approved
• Secure Delivery - HMAC-SHA256 signature verification
• Event Filtering - Subscribe only to events you care about
• Delivery Logging - Track webhook delivery success/failure
• Retry Logic - Automatic retry for failed deliveries

Use Cases

• Crypto Wallet Creation - Create wallets when agents are approved
• Notification Systems - Send alerts to Slack, Discord, or email
• Data Synchronization - Keep external systems in sync
• Analytics Tracking - Log events to analytics platforms
• Workflow Automation - Trigger automated processes

Step 1: Create Your Webhook Endpoint

Create a POST endpoint in your application:

// app/api/webhooks/agentdao/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.AGENTDAO_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', ''), 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

export async function POST(req: NextRequest) {
  try {
    const body = await req.text();
    const signature = req.headers.get('x-webhook-signature');
    const event = req.headers.get('x-webhook-event');

    // Verify webhook signature
    if (!signature || !verifySignature(body, signature)) {
      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
    }

    const payload = JSON.parse(body);
    
    // Handle agent.approved event
    if (event === 'agent.approved') {
      const { data } = payload;
      
      // Create crypto wallet or take other action
      await createCryptoWallet(data);
      
      return NextResponse.json({ success: true });
    }

    return NextResponse.json({ success: true });
    
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

Step 2: Configure Environment Variables

# .env
AGENTDAO_WEBHOOK_SECRET=whsec_your_webhook_secret_here

Step 3: Create Webhook in AgentDAO

1. Go to your AgentDAO dashboard
2. Navigate to Settings → Webhooks
3. Click Create Webhook
4. Enter your webhook URL: https://your-domain.com/api/webhooks/agentdao
5. Select agent.approved event
6. Save the webhook and copy the secret

Step 4: Test Your Webhook

Use the test endpoint to verify your webhook is working:

curl -X POST https://your-domain.com/api/test-webhook \
  -H "Content-Type: application/json" \
  -d '{"event": "agent.approved", "data": {"test": true}}'

Available Events

Webhook Payload Structure

{
  "event": "agent.approved",
  "data": {
    "agent_id": 123,
    "agent_name": "My Agent",
    "agent_url": "myagent.com",
    "developer_id": 456,
    "developer_name": "developer123",
    "description": "Agent description",
    "functionality": "What the agent does",
    "tech_stack": "Technologies used",
    "demo_url": "https://demo.example.com",
    "github_url": "https://github.com/user/repo",
    "approved_at": "2024-01-01T12:00:00.000Z",
    "admin_notes": "Admin approval notes"
  },
  "timestamp": "2024-01-01T12:00:00.000Z",
  "webhook_id": "webhook_123"
}

Webhook Headers

• Content-Type: application/json
• User-Agent: AgentDAO-Webhooks/1.0
• X-Webhook-Signature: sha256=abc123...
• X-Webhook-Event: agent.approved
• X-Webhook-ID: webhook_123

Signature Verification

Every webhook includes an HMAC-SHA256 signature that you must verify:

function verifySignature(payload: string, signature: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', ''), 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Important: Always verify signatures before processing webhooks. Never trust unverified requests.

Security Best Practices

• Verify Signatures - Always check the webhook signature before processing
• Use HTTPS - Only accept webhooks over secure connections
• Rate Limiting - Implement rate limiting on your webhook endpoint
• Timeout Handling - Respond quickly to webhook requests (within 5 seconds)
• Error Logging - Log failed webhook deliveries for debugging
• Secret Management - Store webhook secrets securely in environment variables

Error Handling

export async function POST(req: NextRequest) {
  try {
    const body = await req.text();
    const signature = req.headers.get('x-webhook-signature');

    // Verify signature first
    if (!signature || !verifySignature(body, signature)) {
      console.error('Invalid webhook signature');
      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
    }

    const payload = JSON.parse(body);
    
    // Process webhook
    await processWebhook(payload);
    
    // Always return 200 for successful receipt
    return NextResponse.json({ success: true });
    
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Return 500 to trigger retry
    return NextResponse.json({ error: 'Processing failed' }, { status: 500 });
  }
}

Testing Security

Test your webhook security with these scenarios:

• Send webhook with invalid signature
• Send webhook with missing signature
• Send webhook with wrong HTTP method
• Send webhook with malformed JSON
• Test timeout scenarios