Webhook

概述

通用 Webhook 模块允许您接收来自任何外部服务的 webhook。这是一个灵活的触发器，可以处理任何 JSON 负载，非常适合与没有专用 Sim 模块的服务集成。

基本用法

简单直通模式

在未定义输入格式的情况下，webhook 会按原样传递整个请求正文：

curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'

在下游模块中访问数据：

<webhook1.message> → "测试 webhook 触发器"
<webhook1.data.key> → "值"

结构化输入格式（可选）

定义输入模式以获取类型化字段，并启用高级功能，例如文件上传：

输入格式配置：

[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]

Webhook 请求：

curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'

文件上传

支持的文件格式

webhook 支持两种文件输入格式：

1. Base64 编码文件

用于直接上传文件内容：

{
  "documents": [
    {
      "type": "file",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}

最大大小：每个文件 20MB
格式：带有 base64 编码的标准数据 URL
存储：文件上传到安全的执行存储

2. URL 引用

用于传递现有文件的 URL：

{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}

在下游模块中访问文件

文件被处理为 UserFile 对象，具有以下属性：

{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}

在模块中访问：

<webhook1.documents[0].url> → 下载 URL
<webhook1.documents[0].name> → "invoice.pdf"
<webhook1.documents[0].size> → 524288
<webhook1.documents[0].type> → "application/pdf"

完整的文件上传示例

# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'

身份验证

配置身份验证（可选）

在 webhook 配置中：

启用“需要身份验证”
设置一个密钥令牌
选择头类型：
- 自定义头：X-Sim-Secret: your-token
- 授权 Bearer：Authorization: Bearer your-token

使用身份验证

# With custom header
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'

最佳实践

使用输入格式定义结构：当您知道预期的模式时，定义一个输入格式。这可以提供：
- 类型验证
- 编辑器中的更好自动完成
- 文件上传功能
身份验证：在生产环境的 webhook 中始终启用身份验证，以防止未经授权的访问。
文件大小限制：将文件保持在 20MB 以下。对于更大的文件，请使用 URL 引用。
文件过期：下载的文件具有 5 分钟的过期 URL。请及时处理，或者如果需要更长时间，请将其存储在其他地方。
错误处理：Webhook 处理是异步的。请检查执行日志以获取错误信息。
测试：在部署之前，使用编辑器中的“测试 Webhook”按钮验证您的配置。

使用场景

表单提交：接收带有文件上传的自定义表单数据
第三方集成：与发送 webhook 的服务（如 Stripe、GitHub 等）连接
文档处理：接受来自外部系统的文档进行处理
事件通知：接收来自各种来源的事件数据
自定义 API：为您的应用程序构建自定义 API 端点

注意事项

类别：triggers
类型：generic_webhook
文件支持：通过输入格式配置可用
最大文件大小：每个文件 20MB

Webhook

On this page