创建 Webhook

POST /v1/webhooks

注册一个 Webhook URL，在提取事件发生时接收 POST 请求。每个用户最多可以拥有 10 个活跃的 Webhook。

试一试

在 Swagger UI 中交互式测试此端点。

需要认证

在 Authorization 头中包含您的 API 密钥。

请求

请求头

头	值	必需
Authorization	Bearer <token>	是
Content-Type	application/json	是

请求体

字段	类型	必需	描述
url	string	是	接收 Webhook POST 请求的 HTTPS 端点。
events	string[]	是	要订阅的事件。至少需要一个。可选值："extraction.completed"、"extraction.failed"。

代码示例

curl

curl -X POST https://api.docmap.io/v1/webhooks \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/docmap",
    "events": ["extraction.completed", "extraction.failed"]
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/docmap',
    events: ['extraction.completed', 'extraction.failed'],
  }),
})

const { data } = await response.json()

// IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
console.log('Signing Secret:', data.secret)
console.log('Webhook ID:', data.webhook.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.post(
    "https://api.docmap.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/docmap",
        "events": ["extraction.completed", "extraction.failed"],
    },
)

data = response.json()["data"]

# IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

响应

状态码：200 OK

响应体包含在 data 对象中。

WARNING

签名密钥仅在此响应中返回。请立即安全存储 -- 之后无法再次获取。您需要它来验证 Webhook 签名。

字段

字段	类型	描述
secret	string	HMAC-SHA256 签名密钥（64 个十六进制字符）。仅显示一次。
webhook	object	Webhook 元数据对象（详见下方）。

webhook 对象：

字段	类型	描述
id	string	Webhook 的唯一标识符。
userId	string	拥有该 Webhook 的用户 ID。
url	string	注册的端点 URL。
events	string[]	Webhook 订阅的事件。
active	boolean	Webhook 是否处于活跃状态。新创建的 Webhook 始终为 true。
createdAt	string	Webhook 创建时间的 ISO 8601 时间戳。

示例

{
  "data": {
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "webhook": {
      "id": "webhook-abc123def456",
      "userId": "uid_a1b2c3d4e5f6",
      "url": "https://your-app.com/webhooks/docmap",
      "events": ["extraction.completed", "extraction.failed"],
      "active": true,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  }
}

错误

状态码	错误码	描述
400	MAX_WEBHOOKS_REACHED	您已达到 10 个活跃 Webhook 的上限。请先删除现有 Webhook 再创建新的。
401	UNAUTHORIZED	缺少、无效或已过期的 API 密钥/令牌。