veyra-webhooks

Una herramienta MCP de retransmisión de webhooks para agentes de IA. Registra URLs de destino, envía cargas útiles (payloads) mediante HTTP y explora el historial de envíos. Las lecturas son siempre gratuitas. Las operaciones de escritura requieren autorización en modo de confirmación de Veyra.

Descripción general

veyra-webhooks permite a los agentes de IA interactuar con servicios externos a través de puntos de conexión de webhook registrados. El historial se guarda en SQLite para auditoría. El envío de cargas útiles y la gestión de registros requieren el modo de confirmación de Veyra.

Instalación

npm install
npm run build

Los datos se almacenan en ~/.veyra-webhooks/data.db, creado automáticamente en la primera ejecución.

Configuración de MCP (Claude Desktop)

{
  "mcpServers": {
    "veyra-webhooks": {
      "command": "node",
      "args": ["/absolute/path/to/veyra-webhooks/dist/index.js"]
    }
  }
}

Herramientas

Ejemplos

Lectura (no se necesita token)

// List all registered webhooks
{ "tool": "list_webhooks", "arguments": {} }

// View send history
{ "tool": "get_history", "arguments": { "webhook_id": "1712345678-abc1234", "limit": 20 } }

Escritura (se requiere token de Veyra)

// Register a webhook
{
  "tool": "register_webhook",
  "arguments": {
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/...",
    "headers": "{\"Authorization\": \"Bearer token123\"}",
    "veyra_token": "vt_..."
  }
}

// Send a payload (actually fires an HTTP request)
{
  "tool": "send_webhook",
  "arguments": {
    "webhook_id": "1712345678-abc1234",
    "payload": "{\"text\": \"Deployment complete\"}",
    "method": "POST",
    "veyra_token": "vt_..."
  }
}

// Delete a webhook (also clears its history)
{
  "tool": "delete_webhook",
  "arguments": {
    "webhook_id": "1712345678-abc1234",
    "veyra_token": "vt_..."
  }
}

Respuesta de error cuando falta el token

{
  "error": "VeyraCommitRequired",
  "message": "Write operations require Veyra commit mode.",
  "currentMode": "open",
  "requiredMode": "commit",
  "authorize_endpoint": "https://api.veyra.to/v1/authorize-action",
  "docs_url": "https://veyra.to"
}

Cómo funciona Veyra

Veyra es una capa de autorización en modo de confirmación para agentes de IA. Cuando un agente intenta realizar una escritura:

1. El agente llama a la herramienta sin veyra_token → recibe VeyraCommitRequired con authorize_endpoint.

2. El agente/usuario llama al punto de conexión de autorización para obtener un token.

3. El agente vuelve a intentarlo con veyra_token configurado.

4. veyra-webhooks verifica el token a través de @veyrahq/sdk-node antes de ejecutar la acción.

Consulta veyra.to para obtener la documentación completa.

Licencia

MIT