Webhooks

Integrate external systems with Moxxy via webhooks.

Overview

Webhooks allow external services to trigger your agents via HTTP requests.

┌─────────────┐     HTTP POST      ┌─────────────┐     ┌─────────────┐
│   External  │ ──────────────────▶│   Moxxy     │ ──▶ │   Agent     │
│   Service   │   /webhooks/...    │   Gateway   │     │   Response  │
└─────────────┘                    └─────────────┘     └─────────────┘

Webhook Endpoints

Generic Webhook

POST /api/webhooks/generic

Send a message to an agent:

curl -X POST http://localhost:17890/api/webhooks/generic \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret" \
  -d '{
    "agent": "default",
    "message": "Process this data",
    "context": {
      "source": "external_service",
      "event_id": "12345"
    }
  }'

Platform Webhooks

Telegram

POST /api/webhooks/telegram

Receives Telegram updates when using webhook mode.

Slack

POST /api/webhooks/slack
POST /api/webhooks/slack/interactive

Receives Slack events and interactive component callbacks.

Discord

POST /api/webhooks/discord

Receives Discord interactions.

Authentication

Secret Key

Protect webhooks with a secret key:

# Set webhook secret
moxxy run --agent default --prompt "Store 'my-secret-key' in vault as webhook_secret"

Include in requests:

curl -X POST http://localhost:17890/api/webhooks/generic \
  -H "X-Webhook-Secret: my-secret-key" \
  -d '{"agent": "default", "message": "Hello"}'

IP Whitelisting

Restrict by source IP:

moxxy run --agent default --prompt "Store '192.168.1.0/24,10.0.0.1' in vault as webhook_allowed_ips"

Request Format

Generic Webhook

{
  "agent": "default",           // Target agent name
  "message": "Your message",    // Message to process
  "context": {                  // Optional context
    "source": "service_name",
    "event_type": "alert",
    "custom_field": "value"
  },
  "response_mode": "sync"       // "sync" or "async"
}

Response Modes

Mode	Description
sync	Wait for agent response, return in HTTP response
async	Return immediately, process in background

Response (Sync Mode)

{
  "success": true,
  "agent": "default",
  "response": "I've processed your request...",
  "context": {
    "event_id": "12345"
  }
}

Creating Webhooks

Via API

curl -X POST http://localhost:17890/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-webhook",
    "agent": "default",
    "secret": "github-webhook-secret",
    "transform": {
      "message_template": "GitHub event: {{event_type}} on {{repository}}"
    }
  }'

Webhook Configuration

{
  "name": "alert-webhook",
  "agent": "default",
  "secret": "my-secret",
  "transform": {
    "message_template": "Alert from {{source}}: {{message}}",
    "context_mapping": {
      "severity": "$.severity",
      "service": "$.service_name"
    }
  },
  "filters": {
    "include": ["*.critical", "*.warning"],
    "exclude": ["*.debug"]
  }
}

Use Cases

GitHub Integration

# Create GitHub webhook endpoint
curl -X POST http://localhost:17890/api/webhooks \
  -d '{
    "name": "github",
    "agent": "devops",
    "secret": "github-secret"
  }'

Configure in GitHub:

1. Repository → Settings → Webhooks
2. URL: https://your-server/api/webhooks/github
3. Secret: github-secret
4. Content type: application/json

Monitoring Alerts

# From Prometheus AlertManager
curl -X POST http://localhost:17890/api/webhooks/generic \
  -H "X-Webhook-Secret: alerts-secret" \
  -d '{
    "agent": "ops",
    "message": "Critical alert: High CPU usage on server-1",
    "context": {
      "alert_name": "HighCPU",
      "severity": "critical",
      "instance": "server-1"
    }
  }'

CI/CD Notifications

# From Jenkins/GitLab CI/etc.
curl -X POST http://localhost:17890/api/webhooks/generic \
  -d '{
    "agent": "team",
    "message": "Build #4521 completed successfully",
    "context": {
      "build_id": "4521",
      "status": "success",
      "branch": "main"
    }
  }'

Custom Triggers

# Custom application trigger
curl -X POST http://localhost:17890/api/webhooks/generic \
  -d '{
    "agent": "assistant",
    "message": "New user registration: user@example.com",
    "context": {
      "event": "user_registered",
      "email": "user@example.com"
    }
  }'

Transform Templates

Message Templates

Use Jinja2-style templates:

{
  "transform": {
    "message_template": "Alert: {{alert_name}} on {{instance}} ({{severity}})"
  }
}

Given payload:

{
  "alert_name": "HighCPU",
  "instance": "server-1",
  "severity": "critical"
}

Produces:

Alert: HighCPU on server-1 (critical)

Context Mapping

Extract values from payload:

{
  "transform": {
    "context_mapping": {
      "service": "$.labels.service",
      "severity": "$.status"
    }
  }
}

Filters

Include/Exclude Patterns

{
  "filters": {
    "include": ["*.critical", "*.warning"],
    "exclude": ["test.*"]
  }
}

Conditional Processing

Only process matching events:

{
  "filters": {
    "condition": "$.severity == 'critical'"
  }
}

API Reference

List Webhooks

GET /api/webhooks

Response:

{
  "webhooks": [
    {
      "name": "github",
      "agent": "devops",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Get Webhook

GET /api/webhooks/:name

Create Webhook

POST /api/webhooks

Update Webhook

PUT /api/webhooks/:name

Delete Webhook

DELETE /api/webhooks/:name

Trigger Webhook

POST /api/webhooks/:name/trigger

Security Best Practices

1. Always use secrets - Never accept unauthenticated webhooks
2. Use HTTPS - Encrypt traffic to webhook endpoints
3. Validate payloads - Check structure before processing
4. Rate limit - Prevent abuse
5. Log requests - Audit trail for debugging
6. Use IP whitelists - Restrict to known sources

Troubleshooting

401 Unauthorized

• Check secret key in header
• Verify vault configuration
• Compare with configured secret

404 Not Found

• Verify webhook name
• Check webhook exists: GET /api/webhooks

Timeout

• Use async mode for slow operations
• Increase timeout in configuration
• Check agent processing time

Filtered Out

• Check filter patterns
• Verify payload structure
• Review filter logs