---
title: Webhook
description: 通过配置自定义 webhook，从任何服务接收 webhook。
---

import { BlockInfoCard } from "@/components/ui/block-info-card"
import { Image } from '@/components/ui/image'

<BlockInfoCard 
  type="generic_webhook"
  color="#10B981"
/>

<div className="flex justify-center">
  <Image
    src="/static/blocks/webhook.png"
    alt="Webhook Block Configuration"
    width={500}
    height={400}
    className="my-6"
  />
</div>

## 概述

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

## 基本用法

### 简单直通模式

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

```bash
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>` → "值"

### 结构化输入格式（可选）

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

**输入格式配置：**

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

**Webhook 请求：**

```bash
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 编码文件
用于直接上传文件内容：

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

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

#### 2. URL 引用
用于传递现有文件 URL：

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

### 在下游模块中访问文件

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

```typescript
{
  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"

### 完整文件上传示例

```bash
# 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 配置中：
1. 启用“需要身份验证”
2. 设置一个密钥令牌
3. 选择头类型：
   - **自定义头**: `X-Sim-Secret: your-token`
   - **授权 Bearer**: `Authorization: Bearer your-token`

### 使用身份验证

```bash
# 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"}'
```

## 最佳实践

1. **使用输入格式定义结构**：当您知道预期的模式时，定义输入格式。这提供：
   - 类型验证
   - 编辑器中的更好自动完成
   - 文件上传功能

2. **身份验证**：在生产环境的 webhook 中始终启用身份验证，以防止未经授权的访问。

3. **文件大小限制**：将文件保持在 20MB 以下。对于更大的文件，请使用 URL 引用。

4. **文件过期**：下载的文件具有 5 分钟的 URL 过期时间。请及时处理，或如果需要更长时间，请将其存储在其他地方。

5. **错误处理**：Webhook 处理是异步的。请检查执行日志以获取错误信息。

6. **测试**：在部署前，使用编辑器中的“测试 Webhook”按钮验证您的配置。

## 使用场景

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

## 注意事项

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