|
| 1 | +# Webhook Notification Plugin |
| 2 | + |
| 3 | +> Author: Claude Code Assistant |
| 4 | +> Version: 1.0.0 |
| 5 | +
|
| 6 | +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. |
| 7 | + |
| 8 | +## Hooks |
| 9 | +- `prompt_pre_fetch` |
| 10 | +- `prompt_post_fetch` |
| 11 | +- `tool_pre_invoke` |
| 12 | +- `tool_post_invoke` |
| 13 | +- `resource_pre_fetch` |
| 14 | +- `resource_post_fetch` |
| 15 | + |
| 16 | +## Event Types |
| 17 | +- `violation` - General plugin violations |
| 18 | +- `rate_limit_exceeded` - Rate limiting violations |
| 19 | +- `pii_detected` - PII detection violations |
| 20 | +- `harmful_content` - Harmful content violations |
| 21 | +- `tool_success` - Successful tool invocations |
| 22 | +- `tool_error` - Failed tool invocations |
| 23 | +- `prompt_success` - Successful prompt fetches |
| 24 | +- `resource_success` - Successful resource fetches |
| 25 | +- `plugin_error` - Plugin execution errors |
| 26 | + |
| 27 | +## Authentication Methods |
| 28 | +- `none` - No authentication |
| 29 | +- `bearer` - Bearer token authentication |
| 30 | +- `api_key` - API key in custom header |
| 31 | +- `hmac` - HMAC signature authentication |
| 32 | + |
| 33 | +## Configuration |
| 34 | + |
| 35 | +### Basic Configuration |
| 36 | +```yaml |
| 37 | +config: |
| 38 | + webhooks: |
| 39 | + - url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" |
| 40 | + events: ["violation", "rate_limit_exceeded"] |
| 41 | + authentication: |
| 42 | + type: "none" |
| 43 | + retry_attempts: 3 |
| 44 | + retry_delay: 1000 |
| 45 | + timeout: 10 |
| 46 | + enabled: true |
| 47 | +``` |
| 48 | +
|
| 49 | +### Advanced Configuration with Authentication |
| 50 | +```yaml |
| 51 | +config: |
| 52 | + webhooks: |
| 53 | + # Slack webhook for violations |
| 54 | + - url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" |
| 55 | + events: ["violation", "pii_detected", "harmful_content"] |
| 56 | + authentication: |
| 57 | + type: "bearer" |
| 58 | + token: "${env.SLACK_WEBHOOK_TOKEN}" |
| 59 | + retry_attempts: 3 |
| 60 | + retry_delay: 1000 |
| 61 | + |
| 62 | + # API endpoint with HMAC authentication |
| 63 | + - url: "https://api.example.com/webhooks/mcp-gateway" |
| 64 | + events: ["tool_success", "tool_error"] |
| 65 | + authentication: |
| 66 | + type: "hmac" |
| 67 | + hmac_secret: "${env.WEBHOOK_HMAC_SECRET}" |
| 68 | + hmac_algorithm: "sha256" |
| 69 | + hmac_header: "X-Hub-Signature-256" |
| 70 | + retry_attempts: 5 |
| 71 | + retry_delay: 2000 |
| 72 | + timeout: 30 |
| 73 | + |
| 74 | + # Monitoring service with API key |
| 75 | + - url: "https://monitoring.service.com/events" |
| 76 | + events: ["violation", "tool_error", "plugin_error"] |
| 77 | + authentication: |
| 78 | + type: "api_key" |
| 79 | + api_key: "${env.MONITORING_API_KEY}" |
| 80 | + api_key_header: "X-API-Key" |
| 81 | + retry_attempts: 2 |
| 82 | + retry_delay: 500 |
| 83 | + |
| 84 | + # Custom payload templates per event type |
| 85 | + payload_templates: |
| 86 | + violation: | |
| 87 | + { |
| 88 | + "alert": "MCP Gateway Violation", |
| 89 | + "severity": "warning", |
| 90 | + "message": "{{violation.reason}}: {{violation.description}}", |
| 91 | + "plugin": "{{plugin_name}}", |
| 92 | + "timestamp": "{{timestamp}}", |
| 93 | + "request_id": "{{request_id}}", |
| 94 | + "user": "{{user}}", |
| 95 | + "details": {{violation}} |
| 96 | + } |
| 97 | +
|
| 98 | + rate_limit_exceeded: | |
| 99 | + { |
| 100 | + "alert": "Rate Limit Exceeded", |
| 101 | + "severity": "error", |
| 102 | + "message": "Rate limit exceeded for {{user}}", |
| 103 | + "timestamp": "{{timestamp}}", |
| 104 | + "request_id": "{{request_id}}", |
| 105 | + "violation_details": {{violation}} |
| 106 | + } |
| 107 | +
|
| 108 | + # Include request payload data in notifications (be careful with sensitive data) |
| 109 | + include_payload_data: false |
| 110 | + max_payload_size: 1000 |
| 111 | +``` |
| 112 | +
|
| 113 | +## Template Variables |
| 114 | +
|
| 115 | +The following variables are available in payload templates: |
| 116 | +
|
| 117 | +- `{{event}}` - Event type (violation, tool_success, etc.) |
| 118 | +- `{{plugin_name}}` - Name of the webhook plugin |
| 119 | +- `{{timestamp}}` - ISO timestamp of the event |
| 120 | +- `{{request_id}}` - Unique request identifier |
| 121 | +- `{{user}}` - User identifier (if available) |
| 122 | +- `{{tenant_id}}` - Tenant identifier (if available) |
| 123 | +- `{{server_id}}` - Server identifier (if available) |
| 124 | +- `{{violation}}` - Full violation object (JSON) |
| 125 | +- `{{metadata}}` - Event metadata (JSON) |
| 126 | +- `{{payload}}` - Request payload data (if enabled, JSON) |
| 127 | + |
| 128 | +## Features |
| 129 | + |
| 130 | +### Retry Logic |
| 131 | +- Configurable retry attempts (0-10) |
| 132 | +- Exponential backoff starting from configured delay |
| 133 | +- Individual timeout per webhook request |
| 134 | +- Comprehensive error logging |
| 135 | + |
| 136 | +### Authentication Support |
| 137 | +- **Bearer Token**: `Authorization: Bearer <token>` |
| 138 | +- **API Key**: Custom header with API key |
| 139 | +- **HMAC**: Request signing with configurable algorithm |
| 140 | +- **Environment Variables**: Secure credential management |
| 141 | + |
| 142 | +### Event Filtering |
| 143 | +- Subscribe to specific event types per webhook |
| 144 | +- Smart event detection based on violation details |
| 145 | +- Separate templates for different event types |
| 146 | + |
| 147 | +### Concurrent Delivery |
| 148 | +- Multiple webhooks sent concurrently |
| 149 | +- Non-blocking execution (fire-and-forget) |
| 150 | +- Individual retry logic per webhook |
| 151 | + |
| 152 | +## Security Considerations |
| 153 | + |
| 154 | +1. **Credential Management**: Use environment variables for sensitive data |
| 155 | +2. **Payload Size**: Limit included payload data to prevent sensitive data leaks |
| 156 | +3. **HMAC Signatures**: Verify webhook authenticity on receiving end |
| 157 | +4. **Network Security**: Use HTTPS endpoints only |
| 158 | +5. **Timeout Configuration**: Prevent hanging requests |
| 159 | + |
| 160 | +## Example Webhook Payloads |
| 161 | + |
| 162 | +### Violation Event |
| 163 | +```json |
| 164 | +{ |
| 165 | + "event": "violation", |
| 166 | + "plugin": "WebhookNotificationPlugin", |
| 167 | + "timestamp": "2025-01-15T10:30:45.123Z", |
| 168 | + "request_id": "req-12345", |
| 169 | + |
| 170 | + "tenant_id": "tenant-abc", |
| 171 | + "server_id": "server-xyz", |
| 172 | + "violation": { |
| 173 | + "reason": "Rate limit exceeded", |
| 174 | + "description": "User [email protected] rate limit exceeded", |
| 175 | + "code": "RATE_LIMIT", |
| 176 | + "details": {"remaining": 0, "reset_in": 45} |
| 177 | + }, |
| 178 | + "metadata": {} |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +### Tool Success Event |
| 183 | +```json |
| 184 | +{ |
| 185 | + "event": "tool_success", |
| 186 | + "plugin": "WebhookNotificationPlugin", |
| 187 | + "timestamp": "2025-01-15T10:30:45.123Z", |
| 188 | + "request_id": "req-12346", |
| 189 | + |
| 190 | + "violation": null, |
| 191 | + "metadata": {"tool_name": "search"} |
| 192 | +} |
| 193 | +``` |
| 194 | + |
| 195 | +## Usage Tips |
| 196 | + |
| 197 | +1. **Start Simple**: Begin with basic Slack webhooks for violations |
| 198 | +2. **Test Thoroughly**: Use tools like ngrok for local webhook testing |
| 199 | +3. **Monitor Logs**: Check gateway logs for webhook delivery status |
| 200 | +4. **Gradual Rollout**: Enable events incrementally to avoid notification spam |
| 201 | +5. **Template Testing**: Test payload templates with various event types |
| 202 | + |
| 203 | +## Performance Notes |
| 204 | + |
| 205 | +- Webhooks are sent asynchronously and don't block request processing |
| 206 | +- Failed webhooks are retried with exponential backoff |
| 207 | +- HTTP client connection pooling optimizes performance |
| 208 | +- Memory usage scales with number of concurrent webhook deliveries |
| 209 | + |
| 210 | +## Troubleshooting |
| 211 | + |
| 212 | +### Common Issues |
| 213 | +- **Authentication Failures**: Verify tokens and secrets in environment variables |
| 214 | +- **Timeout Errors**: Increase timeout values for slow webhook endpoints |
| 215 | +- **Template Errors**: Check Jinja2 syntax in custom templates |
| 216 | +- **SSL Errors**: Ensure webhook URLs use valid HTTPS certificates |
| 217 | + |
| 218 | +### Debug Logging |
| 219 | +Enable debug logging to see webhook delivery attempts: |
| 220 | +```bash |
| 221 | +export LOG_LEVEL=DEBUG |
| 222 | +``` |
0 commit comments