route.ts

route.ts

基本信息

  • 类型: API 路由
  • 路径: ./src/app/api/admin/webhooks/route.ts
  • 路由: /api/admin/webhooks

概述

管理员 Webhook 管理接口。支持查看和创建 Webhook 配置，用于在 Prompt 发生变化时通知外部系统。

HTTP 方法

  • GET: 获取所有 Webhook 配置
  • POST: 创建新的 Webhook 配置

GET - 获取所有 Webhook

响应

成功 (200)

[
  {
    "id": "webhook_id",
    "name": "Webhook 名称",
    "url": "https://example.com/webhook",
    "method": "POST",
    "headers": {
      "X-Custom-Header": "value"
    },
    "payload": "{ \"event\": \"{{event}}\", \"data\": {{data}} }",
    "events": ["PROMPT_CREATED", "PROMPT_UPDATED"],
    "isEnabled": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

未授权 (401)

{
  "error": "unauthorized"
}

服务器错误 (500)

{
  "error": "server_error"
}

POST - 创建 Webhook

Body 参数

参数类型必填说明
namestring是Webhook 名称，1-100 字符
urlstring是Webhook URL
methodstring否HTTP 方法: GET, POST, PUT, PATCH，默认 POST
headersobject否自定义请求头
payloadstring是请求体模板
eventsstring[]是订阅的事件类型
isEnabledboolean否是否启用，默认 true

支持的事件类型

  • PROMPT_CREATED: Prompt 创建时触发
  • PROMPT_UPDATED: Prompt 更新时触发
  • PROMPT_DELETED: Prompt 删除时触发

Payload 模板变量

  • {{event}}: 事件类型
  • {{data}}: 事件数据（JSON）

响应

成功 (200)

返回创建的 Webhook 配置对象

错误

未授权 (401)
{
  "error": "unauthorized"
}
验证失败 (400)
{
  "error": "validation_error",
  "message": "错误详情"
}

可能的验证错误：

  • Name is required (1-100 characters)
  • URL is required
  • Invalid URL
  • Webhook URL cannot target private/internal networks
  • Invalid method
  • Payload is required
  • At least one event is required
  • Invalid event: xxx
服务器错误 (500)
{
  "error": "server_error"
}

依赖

  • next/server - Next.js 服务器组件
  • @/lib/auth - 认证
  • @/lib/db - Prisma 数据库客户端
  • @/lib/webhook - Webhook 工具（SSRF 防护）

权限

  • 需要管理员角色 (role === "ADMIN")

安全特性

  1. SSRF 防护: 禁止访问私有/内部网络地址
  2. URL 验证: 必须有效的 HTTP/HTTPS URL
  3. 事件白名单: 只允许预定义的事件类型
  4. 方法白名单: 只允许安全的 HTTP 方法
← 返回目录