Webhooks API

Create and manage webhooks for external integrations.

List Webhooks

GET /api/webhooks

Response

{
  "webhooks": [
    {
      "name": "github",
      "agent": "devops",
      "created_at": "2024-01-15T10:00:00Z",
      "last_triggered": "2024-01-15T12:00:00Z",
      "trigger_count": 42
    },
    {
      "name": "alerts",
      "agent": "ops",
      "created_at": "2024-01-15T11:00:00Z",
      "last_triggered": null,
      "trigger_count": 0
    }
  ]
}

Get Webhook

GET /api/webhooks/:name

Response

{
  "name": "github",
  "agent": "devops",
  "secret": "***",
  "transform": {
    "message_template": "GitHub: {{event_type}} on {{repository}}"
  },
  "filters": {
    "include": ["push", "pull_request"]
  },
  "created_at": "2024-01-15T10:00:00Z",
  "last_triggered": "2024-01-15T12:00:00Z",
  "trigger_count": 42
}

Create Webhook

POST /api/webhooks

Request

{
  "name": "github-webhook",
  "agent": "devops",
  "secret": "github-webhook-secret",
  "transform": {
    "message_template": "GitHub event: {{event_type}} from {{sender.login}}",
    "context_mapping": {
      "repository": "$.repository.full_name",
      "branch": "$.ref"
    }
  },
  "filters": {
    "include": ["push", "pull_request.opened"],
    "exclude": ["push.*.gh-pages"]
  },
  "response_mode": "async"
}

Parameters

Field	Type	Required	Description
name	string	Yes	Webhook identifier
agent	string	Yes	Target agent
secret	string	Yes	Authentication secret
transform	object	No	Message transformation config
filters	object	No	Event filtering rules
response_mode	string	No	"sync" or "async" (default: async)

Response

{
  "success": true,
  "webhook": {
    "name": "github-webhook",
    "url": "/api/webhooks/trigger/github-webhook",
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Update Webhook

PUT /api/webhooks/:name

Request

{
  "agent": "new-agent",
  "transform": {
    "message_template": "Updated template: {{event}}"
  }
}

Delete Webhook

DELETE /api/webhooks/:name

Response

{
  "success": true,
  "message": "Webhook 'old-webhook' deleted"
}

Trigger Webhook

Generic Trigger

POST /api/webhooks/:name/trigger

Request

{
  "payload": {
    "event_type": "push",
    "repository": "user/repo",
    "sender": {
      "login": "username"
    }
  }
}

Response (Async Mode)

{
  "success": true,
  "message": "Webhook triggered",
  "trigger_id": "trig_abc123"
}

Response (Sync Mode)

{
  "success": true,
  "agent_response": "I've processed the push event...",
  "processing_time_ms": 1500
}

Generic Webhook Endpoint

POST /api/webhooks/generic

Send directly to an agent without creating a webhook.

Request

{
  "agent": "default",
  "message": "External event occurred",
  "context": {
    "source": "external_service",
    "event_id": "12345"
  },
  "secret": "your-webhook-secret"
}

Response

{
  "success": true,
  "response": "I've processed the event..."
}

Platform Webhooks

Telegram Webhook

POST /api/webhooks/telegram

Receives Telegram Update objects.

Slack Webhook

POST /api/webhooks/slack

Receives Slack event payloads.

Slack Interactive

POST /api/webhooks/slack/interactive

Receives Slack interactive component callbacks.

Discord Webhook

POST /api/webhooks/discord

Receives Discord interaction payloads.

Transform Configuration

Message Templates

Use Jinja2-style syntax:

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

Available in payload:

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

Result:

Alert: HighCPU (critical) on server-1

Context Mapping

Extract values using JSONPath:

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

Default Values

{
  "transform": {
    "message_template": "Event: {{event_type | default('unknown')}}"
  }
}

Filter Configuration

Include Patterns

Only process matching events:

{
  "filters": {
    "include": ["push", "pull_request.*", "issues.opened"]
  }
}

Exclude Patterns

Skip matching events:

{
  "filters": {
    "exclude": ["*.bot", "push.gh-pages"]
  }

Conditional Filters

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

Webhook Logs

Get Webhook Logs

GET /api/webhooks/:name/logs

Response

{
  "logs": [
    {
      "timestamp": "2024-01-15T12:00:00Z",
      "trigger_id": "trig_abc123",
      "success": true,
      "processing_time_ms": 1500
    }
  ]
}

Security

HMAC Verification

For services that use HMAC signatures:

POST /api/webhooks/:name/verify

Request

{
  "signature": "sha256=...",
  "payload": {...}
}

IP Whitelist

Configure allowed source IPs:

{
  "security": {
    "allowed_ips": ["192.168.1.0/24", "10.0.0.1"]
  }
}