Webhook API

Integrate Valgent validation into your CI/CD pipelines with webhooks.

Overview

Webhooks allow you to integrate agent card validation into your development workflow:

• CI/CD Integration: Validate agent cards as part of your build process
• Asynchronous Processing: Get immediate response, receive results via callback
• GitHub Integration: Specialized endpoint for GitHub workflows
• Metadata Support: Include repository, commit, and PR information

Authentication

Webhook endpoints are public and do not require API keys, making them suitable for CI/CD environments.

Endpoints

Generic Webhook

POST /v1/webhook

General-purpose webhook endpoint for any CI/CD system.

Authentication: None required

Request Body:

{
  "agent_card": {
    "protocolVersion": "0.2.6",
    "name": "My Agent",
    "description": "Agent description",
    // ... rest of agent card
  },
  "callback_url": "https://your-server.com/webhook-callback",
  "metadata": {
    "repo": "username/repo-name",
    "commit": "abc123def456",
    "branch": "main",
    "author": "developer@example.com",
    "pull_request": 42
  }
}

Parameters:

• agent_card (required): The agent card JSON to validate
• callback_url (optional): URL to receive validation results
• metadata (optional): Additional context information
  • repo (string): Repository identifier
  • commit (string): Commit hash
  • branch (string): Branch name
  • author (string): Author email or username
  • pull_request (number): Pull request number

Synchronous Response (when no callback_url):

{
  "validation_id": "val_1705312200000_abc123",
  "status": "success",
  "valid": true,
  "score": 88,
  "errors": [],
  "warnings": [
    {
      "path": "description",
      "message": "Description could be more detailed"
    }
  ],
  "suggestions": [
    {
      "type": "improvement",
      "field": "tags",
      "suggestion": "Consider adding more specific tags"
    }
  ],
  "metadata": {
    "repo": "username/repo-name",
    "commit": "abc123def456",
    "branch": "main",
    "author": "developer@example.com",
    "pull_request": 42
  },
  "report_url": "https://valgent.io/reports/val_1705312200000_abc123",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Asynchronous Response (when callback_url provided):

{
  "message": "Validation started",
  "validation_id": "val_1705312200000_abc123",
  "status_url": "https://api.valgent.io/v1/status/val_1705312200000_abc123"
}

The validation results will be sent to your callback_url with the same format as the synchronous response.

GitHub Webhook

POST /v1/webhook/github

Specialized webhook endpoint optimized for GitHub workflows and Actions.

Authentication: None required

Request Body:

{
  "agent_card": {
    "protocolVersion": "0.2.6",
    "name": "My Agent",
    "description": "Agent description",
    // ... rest of agent card
  },
  "github": {
    "repo": "username/repo-name",
    "sha": "abc123def456789"
  }
}

Parameters:

• agent_card (required): The agent card JSON to validate
• github (required): GitHub-specific context
  • repo (required): Repository name in owner/repo format
  • sha (required): Full commit SHA hash

Response:

{
  "success": true,
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": [
      {
        "path": "description",
        "message": "Description could be more detailed"
      }
    ]
  },
  "score": 92,
  "github_status": {
    "state": "success",
    "description": "Agent card valid (score: 92/100)",
    "context": "valgent/validation",
    "target_url": "https://valgent.io/reports/abc123def456789"
  }
}

The github_status object contains information that can be used to update GitHub commit status via the GitHub API.

Error Responses

Security Considerations

Callback URL Validation

Since webhook endpoints are public, validate callback URLs in production:

• Use HTTPS endpoints only
• Implement proper authentication for your callback endpoints
• Validate webhook signatures if implementing custom verification

Rate Limiting

Webhook endpoints have built-in rate limiting:

• Per IP: 100 requests per minute
• Global: 10,000 requests per hour

Timeout Handling

• Webhook validation has a 30-second timeout
• Callback delivery has a 10-second timeout
• Failed callbacks are not retried

Best Practices

1. Error Handling

Always check the validation status:

#!/bin/bash
response=$(curl -s -X POST https://api.valgent.io/v1/webhook \
  -H "Content-Type: application/json" \
  -d @payload.json)

if echo "$response" | jq -e '.valid == false' > /dev/null; then
  echo "❌ Agent card validation failed"
  echo "$response" | jq '.errors'
  exit 1
else
  echo "✅ Agent card validation passed"
  echo "Score: $(echo "$response" | jq '.score')/100"
fi

2. Metadata Usage

Include meaningful metadata for better tracking:

{
  "metadata": {
    "repo": "company/project",
    "commit": "full-sha-hash",
    "branch": "feature/agent-updates",
    "author": "developer@company.com",
    "pull_request": 123,
    "environment": "staging"
  }
}

3. Callback Endpoints

Make callback endpoints idempotent and handle duplicates:

const processedValidations = new Set();

app.post('/webhook-callback', (req, res) => {
  const { validation_id } = req.body;
  
  if (processedValidations.has(validation_id)) {
    return res.status(200).json({ status: 'already_processed' });
  }
  
  processedValidations.add(validation_id);
  
  // Process validation result
  // ...
  
  res.status(200).json({ status: 'processed' });
});

Troubleshooting

Common Issues

1. 400 Bad Request: Check that agent_card is included in request body
2. Callback Not Received: Verify callback URL is accessible and uses HTTPS
3. Timeout Errors: Large agent cards may take longer to validate
4. Rate Limit: Implement backoff and retry logic

Debug Mode

Add debug information to your requests:

{
  "agent_card": { /* ... */ },
  "callback_url": "https://your-server.com/debug-callback",
  "metadata": {
    "debug": true,
    "environment": "testing"
  }
}