接收入站回调

无需 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

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

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

text/plain

string

application/octet-stream

string

示例

SDK 安装与示例环境

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

变量	来源
TRIGGER_ID	触发器 id；webhook 调用前需恢复启用
WEBHOOK_TOKEN	新 webhook_url 的最后一段；不要公开

: "${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
}'

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

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

{
  "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.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

接收入站回调

application/octet-stream

本页内容