# Webhook Notification Plugin
> Author: Manav Gupta
> Version: 1.0.0
Sends HTTP webhook notifications on specific events, violations, or state changes. Supports multiple webhooks, event filtering, retry logic with exponential backoff, and various authentication methods.
## Hooks
- `prompt_pre_fetch`
- `prompt_post_fetch`
- `tool_pre_invoke`
- `tool_post_invoke`
- `resource_pre_fetch`
- `resource_post_fetch`
## Event Types
- `violation` - General plugin violations
- `rate_limit_exceeded` - Rate limiting violations
- `pii_detected` - PII detection violations
- `harmful_content` - Harmful content violations
- `tool_success` - Successful tool invocations
- `tool_error` - Failed tool invocations
- `prompt_success` - Successful prompt fetches
- `resource_success` - Successful resource fetches
- `plugin_error` - Plugin execution errors
## Authentication Methods
- `none` - No authentication
- `bearer` - Bearer token authentication
- `api_key` - API key in custom header
- `hmac` - HMAC signature authentication
## Configuration
### Basic Configuration
```yaml
config:
webhooks:
- url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
events: ["violation", "rate_limit_exceeded"]
authentication:
type: "none"
retry_attempts: 3
retry_delay: 1000
timeout: 10
enabled: true
```
### Advanced Configuration with Authentication
```yaml
config:
webhooks:
# Slack webhook for violations
- url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
events: ["violation", "pii_detected", "harmful_content"]
authentication:
type: "bearer"
token: "${env.SLACK_WEBHOOK_TOKEN}"
retry_attempts: 3
retry_delay: 1000
# API endpoint with HMAC authentication
- url: "https://api.example.com/webhooks/mcp-gateway"
events: ["tool_success", "tool_error"]
authentication:
type: "hmac"
hmac_secret: "${env.WEBHOOK_HMAC_SECRET}"
hmac_algorithm: "sha256"
hmac_header: "X-Hub-Signature-256"
retry_attempts: 5
retry_delay: 2000
timeout: 30
# Monitoring service with API key
- url: "https://monitoring.service.com/events"
events: ["violation", "tool_error", "plugin_error"]
authentication:
type: "api_key"
api_key: "${env.MONITORING_API_KEY}"
api_key_header: "X-API-Key"
retry_attempts: 2
retry_delay: 500
# Custom payload templates per event type
payload_templates:
violation: |
{
"alert": "MCP Gateway Violation",
"severity": "warning",
"message": "{{violation.reason}}: {{violation.description}}",
"plugin": "{{plugin_name}}",
"timestamp": "{{timestamp}}",
"request_id": "{{request_id}}",
"user": "{{user}}",
"details": {{violation}}
}
rate_limit_exceeded: |
{
"alert": "Rate Limit Exceeded",
"severity": "error",
"message": "Rate limit exceeded for {{user}}",
"timestamp": "{{timestamp}}",
"request_id": "{{request_id}}",
"violation_details": {{violation}}
}
# Include request payload data in notifications (be careful with sensitive data)
include_payload_data: false
max_payload_size: 1000
```
## Template Variables
The following variables are available in payload templates:
- `{{event}}` - Event type (violation, tool_success, etc.)
- `{{plugin_name}}` - Name of the webhook plugin
- `{{timestamp}}` - ISO timestamp of the event
- `{{request_id}}` - Unique request identifier
- `{{user}}` - User identifier (if available)
- `{{tenant_id}}` - Tenant identifier (if available)
- `{{server_id}}` - Server identifier (if available)
- `{{violation}}` - Full violation object (JSON)
- `{{metadata}}` - Event metadata (JSON)
- `{{payload}}` - Request payload data (if enabled, JSON)
## Features
### Retry Logic
- Configurable retry attempts (0-10)
- Exponential backoff starting from configured delay
- Individual timeout per webhook request
- Comprehensive error logging
### Authentication Support
- **Bearer Token**: `Authorization: Bearer <token>`
- **API Key**: Custom header with API key
- **HMAC**: Request signing with configurable algorithm
- **Environment Variables**: Secure credential management
### Event Filtering
- Subscribe to specific event types per webhook
- Smart event detection based on violation details
- Separate templates for different event types
### Concurrent Delivery
- Multiple webhooks sent concurrently
- Non-blocking execution (fire-and-forget)
- Individual retry logic per webhook
## Security Considerations
1. **Credential Management**: Use environment variables for sensitive data
2. **Payload Size**: Limit included payload data to prevent sensitive data leaks
3. **HMAC Signatures**: Verify webhook authenticity on receiving end
4. **Network Security**: Use HTTPS endpoints only
5. **Timeout Configuration**: Prevent hanging requests
## Example Webhook Payloads
### Violation Event
```json
{
"event": "violation",
"plugin": "WebhookNotificationPlugin",
"timestamp": "2025-01-15T10:30:45.123Z",
"request_id": "req-12345",
"user": "user@example.com",
"tenant_id": "tenant-abc",
"server_id": "server-xyz",
"violation": {
"reason": "Rate limit exceeded",
"description": "User user@example.com rate limit exceeded",
"code": "RATE_LIMIT",
"details": {"remaining": 0, "reset_in": 45}
},
"metadata": {}
}
```
### Tool Success Event
```json
{
"event": "tool_success",
"plugin": "WebhookNotificationPlugin",
"timestamp": "2025-01-15T10:30:45.123Z",
"request_id": "req-12346",
"user": "user@example.com",
"violation": null,
"metadata": {"tool_name": "search"}
}
```
## Usage Tips
1. **Start Simple**: Begin with basic Slack webhooks for violations
2. **Test Thoroughly**: Use tools like ngrok for local webhook testing
3. **Monitor Logs**: Check gateway logs for webhook delivery status
4. **Gradual Rollout**: Enable events incrementally to avoid notification spam
5. **Template Testing**: Test payload templates with various event types
## Performance Notes
- Webhooks are sent asynchronously and don't block request processing
- Failed webhooks are retried with exponential backoff
- HTTP client connection pooling optimizes performance
- Memory usage scales with number of concurrent webhook deliveries
## Troubleshooting
### Common Issues
- **Authentication Failures**: Verify tokens and secrets in environment variables
- **Timeout Errors**: Increase timeout values for slow webhook endpoints
- **Template Errors**: Check Jinja2 syntax in custom templates
- **SSL Errors**: Ensure webhook URLs use valid HTTPS certificates
### Debug Logging
Enable debug logging to see webhook delivery attempts:
```bash
export LOG_LEVEL=DEBUG
```
