AuraBoot
免费开始
English简体中文

Webhooks

Webhook 让 AuraBoot 在业务 Event 发生时通知外部系统。它常用于将 AuraBoot 与 CRM、ERP、客服工具、工作流系统、数据管道以及自定义内部服务进行对接。

Event 流转

Command executes
  -> domain event is created
  -> event is stored for reliable delivery
  -> webhook dispatcher matches subscriptions
  -> HTTP POST is sent to target URL
  -> delivery result is logged

运行时应将 Webhook 投递视为 at-least-once。接收方应保证幂等。

订阅模型

一条 Webhook 订阅通常包含：

字段用途
name可读的订阅名称
targetUrl外部端点
eventType监听的 Event
modelCode可选的 model 过滤
filterExpression可选的条件
secretHMAC 签名密钥
maxRetries重试上限
timeoutMs请求超时
enabled投递开关

订阅示例

{
  "name": "Qualified Lead Webhook",
  "targetUrl": "https://example.com/webhooks/aura",
  "eventType": "record.updated",
  "modelCode": "crm_lead",
  "filterExpression": "status == 'qualified'",
  "secret": "replace-with-strong-secret",
  "maxRetries": 3,
  "timeoutMs": 10000,
  "enabled": true
}

负载结构

命令管道在投递 Webhook 时构造的负载包含命令编码、model 编码、命令入参以及命令执行结果，使接收方能够识别操作并获取数据：

{
  "commandCode": "qualify_crm_lead",
  "modelCode": "crm_lead",
  "payload": {
    "status": "qualified"
  },
  "result": {
    "status": "qualified"
  }
}

其中 payload 是命令的入参，result 是命令执行后的字段映射与 handler 结果。

签名校验

当订阅配置了 secret 时，Webhook 请求会使用 HMAC-SHA256 进行签名。接收方使用共享 secret 重新计算 Signature 并拒绝不匹配的请求。

X-Webhook-Event: qualify_crm_lead
X-Webhook-Timestamp: 1747214400000
X-Webhook-Signature: sha256=<hex-digest>

X-Webhook-Event 为订阅监听的 Event（未显式配置时为命令编码），X-Webhook-Timestamp 为投递时刻的 epoch 毫秒，X-Webhook-Signature 仅在配置了 secret 时出现。

重试行为

外部系统可能失败。AuraBoot 应对失败的投递进行带退避的重试。接收方应避免无法容忍重复投递的副作用。

响应行为
2xx标记投递成功
4xx当前调度器仍会按失败投递重试;反复 4xx 通常应排查 URL、鉴权或 payload 契约
5xx重试直到上限
Timeout重试直到上限

安全建议

  • 使用 HTTPS 的目标 URL。
  • 校验 HMAC Signature。
  • 若启用重放保护，拒绝过旧的时间戳。
  • 不要在日志中暴露 Webhook secret。
  • 让接收端 handler 保持幂等。
  • 使用更精细的 Event 过滤，而不是发送所有 Event。

测试

请先使用测试端点：

curl -X POST http://localhost:6443/api/webhooks/<pid>/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sample": true}'

之后在绑定生产工作流之前，先核对投递日志。

下一步