Evose

API · Webhooks

异步事件订阅 · 签名验证 · 重试

Webhooks

让 Evose 主动通知你的业务系统：Workflow 完成、Agent 收到消息、知识库索引就绪等。

工作模式

Evose 端发生事件
    ↓
HTTPS POST 到你配置的 URL
    ↓
你的系统返回 2xx → 完成
你的系统返回 5xx / 超时 → Evose 重试(指数退避,最多 5 次)

注册 Webhook

POST /v1/webhooks
{
  "url": "https://your-server.example.com/evose-webhook",
  "events": ["workflow.run.completed", "workflow.run.failed"],
  "secret": "<openssl rand -hex 32>"
}
字段说明
url接收 URL,必须 HTTPS
events订阅事件类型
secret用于签名验证（必填)

支持的事件

事件触发时机
workflow.run.completedWorkflow 执行成功
workflow.run.failedWorkflow 执行失败
agent.message.receivedAgent 收到用户消息
knowledge.document.ready文档索引完成
knowledge.document.failed文档解析失败
model.failover.triggeredLLM Failover 触发
credit.budget.threshold积分预算触发阈值

事件结构

POST /your-endpoint
Content-Type: application/json
X-Evose-Signature: sha256=abcdef0123...
X-Evose-Event: workflow.run.completed
X-Evose-Delivery-Id: del-xxx
{
  "event": "workflow.run.completed",
  "delivered_at": "2026-05-08T14:30:00Z",
  "data": {
    "workflow_id": "wf-001",
    "run_id": "run-abc",
    "status": "completed",
    "duration_ms": 3200,
    "outputs": { ... }
  }
}

签名验证

防止伪造:

import hmac, hashlib
 
body = request.body  # 原始字节
signature = request.headers['X-Evose-Signature'].split('=')[1]
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
 
if not hmac.compare_digest(signature, expected):
    return 403

重试与幂等

行为说明
你返回 2xx视为成功
你返回 4xx不重试(请求格式问题，你修了再重新订阅)
你返回 5xx / 超时重试 5 次，退避 30s / 1m / 5m / 30m / 2h
你的接收方有故障Evose 把失败 delivery 存 7 天，可在 UI 手动重发

用 X-Evose-Delivery-Id 做幂等

重试时同一事件有相同 Delivery-Id,你的系统应去重处理。

列出 / 删除 Webhook

GET /v1/webhooks
DELETE /v1/webhooks/{id}

看投递记录

GET /v1/webhooks/{id}/deliveries?status=failed

测试触发

POST /v1/webhooks/{id}/ping

发一条 webhook.test 事件，验证你的接收端通畅。

接下来

上一页

API · 模型

页面导航