# 接收入站回调 (/docs/api/native/automation/receiveWebhook)





无需 API Key，以 URL 中 token 鉴权；token 错误、触发器不存在、类型不符或不在时间窗口内均返回 404；触发器处于暂停状态（连续 5 次失败熔断或人工暂停）返回 409 TRIGGER_PAUSED，message 说明原因，hint 给出恢复办法 POST /automation/v1/triggers/{id}/resume。原始请求体上限 512 KiB；组装后的运行输入（含原文与解析后的副本）序列化后最多 1 MiB，超限同步返回 413，不创建触发记录；webhook-id 去重 24 小时。202 的 outcome=accepted 表示已受理，最终结果随后更新，重复请求为 deduped。JSON 解析失败时 body 为 null；其它 UTF-8 为原文，非 UTF-8 为 base64。envelope 包含 body、raw_body、raw_body_encoding、白名单 headers、webhook_id 和 received_at；raw_body 保留原始字节，raw_body_encoding 为 utf8 或 base64，可用于自行验签。

`POST /automation/v1/hooks/{trigger_id}/{token}`

## 鉴权 [#鉴权]

使用创建或轮换时返回的 webhook URL；路径中的 token 是凭据，无需 Bearer Key。

## 请求字段 [#请求字段]

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| path: trigger_id | `string` | 必填；触发器 ID（trg_）。 |
| path: token | `string` | 必填；创建或轮换时返回的私密 URL token；请勿公开。 |
| header: webhook-id | `string` | 可选；可选去重标识，同一触发器内保留 24 小时。 |

### application/json [#applicationjson]

任意 JSON 值：null、布尔、数字、字符串、数组或对象。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| （分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| （分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |

### text/plain [#textplain]

string
### application/octet-stream

string

## 示例 [#示例]

[SDK 安装与示例环境](/docs/api/native/automation)

先设置以下环境变量，使用你自己的资源：

| 变量 | 来源 |
| --- | --- |
| TRIGGER_ID | [触发器 id；webhook 调用前需恢复启用](/docs/api/native/automation/createTrigger) |
| WEBHOOK_TOKEN | [新 webhook_url 的最后一段；不要公开](/docs/api/native/automation/rotateTriggerWebhook) |

```bash
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${WEBHOOK_TOKEN:?Set WEBHOOK_TOKEN}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/hooks/${TRIGGER_ID}/${WEBHOOK_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
  "n": 41
}'
```

```typescript
import { createAutomationClient } from '@deepractice-ai/praxis-sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: '',
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.hooks.send({
  "path": {
    "trigger_id": env("TRIGGER_ID"),
    "token": env("WEBHOOK_TOKEN")
  },
  "body": {
    "n": 41
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 202 [#http-202]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | `string` | 必填 / 必有；触发记录 ID；记录保留 30 天。 |
| trigger_id | `string` | 必填 / 必有；所属触发器 ID（trg_ 前缀）。 |
| scheduled_at | `string` | 必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time" |
| fired_at | `string` | 必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time" |
| outcome | `"accepted"` / `"started"` / `"skipped_overlap"` / `"missed"` / `"failed"` / `"deduped"` | 必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。 |
| run_id | `string` / `null` | 必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。 |
| resolved_version | `string` / `null` | 必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。 |
| error | `object` / `null` | 必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。 |
| error（分支1).code | `string` | 必填 / 必有；失败的错误码。 |
| error（分支1).message | `string` | 必填 / 必有；失败的说明文字。 |

### 实测响应 [#实测响应]

HTTP 202

```json
{
  "id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
  "trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "scheduled_at": "2026-10-13T04:58:18.384Z",
  "fired_at": "2026-10-13T04:58:18.384Z",
  "outcome": "accepted",
  "run_id": null,
  "resolved_version": null,
  "error": null
}
```

## 错误码 [#错误码]

| HTTP | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 |
| 404 | TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。 |
| 405 | METHOD_NOT_ALLOWED：仅支持 POST；其它方法无需鉴权即返回 405，Allow 为 POST。 |
| 409 | TRIGGER_PAUSED：触发器处于暂停状态：连续 5 次触发失败触发熔断自动暂停，或被人工暂停；响应 message 说明原因，hint 给出恢复办法：恢复该触发器（triggers.resume）。 |
| 412 | PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。 |
| 413 | PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

[鉴权错误与通用错误](/docs/api/errors) · 排查时保留响应头 `X-Request-Id`。