Webhook
Webhook 允许外部系统在 EspoCRM 中 订阅事件（创建/更新/删除记录），事件发生时 Espo 向指定 URL POST JSON。
参考：Webhooks（英文）
典型场景
| 场景 | 事件示例 |
|---|---|
| 新订单同步 ERP | CSalesOrder.create |
| 订单状态变更通知 | CSalesOrder.fieldUpdate.status |
| 客户更新同步 | Account.update |
创建 Webhook
管理界面
管理 → Webhook → 创建
| 字段 | 说明 |
|---|---|
| Event | 如 CSalesOrder.create |
| URL | 接收端 HTTPS 地址 |
| Skip Own | 跳过 webhook 所属 API 用户自己触发的事件 |
保存后获得 ID 与 Secret Key（用于验签）。
API 创建（API User）
POST /api/v1/Webhook
Content-Type: application/json
{
"event": "CSalesOrder.create",
"url": "https://your-server.com/hooks/espo"
}
API User 角色需开放 Webhook scope 及对目标实体的读权限。
事件类型
| 模式 | 说明 | 示例 |
|---|---|---|
{Entity}.create |
新建 | CQuote.create |
{Entity}.update |
更新（payload 仅变更字段） | Account.update |
{Entity}.delete |
删除 | CSalesOrder.delete |
{Entity}.fieldUpdate.{field} |
某字段变更 | CSalesOrder.fieldUpdate.status |
可用实体列表：管理 → 实体管理器。Bring 实体均支持标准 CRUD 事件。
请求格式
- 方法：POST
- Content-Type：
application/json - Body：数组（批量），即使一条也是
[{...}]
单条示例：
[
{
"id": "664a1b2c3d4e5f6a7",
"name": "SO-2026-001",
"status": "已下单"
}
]
发送机制
由计划任务 Process Webhook Queue 处理（默认约每 5 分钟）。
管理 → 计划任务 可改频率。队列项：Webhook → 右上角菜单 → Webhook Queue Items。
验签 Signature
接收端验证 Header Signature（v9.0+）：
$signature = base64_encode($webhookId . ':' . hash_hmac('sha256', $payload, $secretKey));
$payload= 原始 POST body 字符串$webhookId、$secretKey来自 Webhook 记录
错误与重试
| HTTP 结果 | 行为 |
|---|---|
| 400, 401, 403, 404, 405, 408, 超时 | 重试 |
| 410 | 立即删除 webhook |
| 其他 | 按 maxAttemptNumber 重试 |
配置项见 data/config.php：webhookMaxAttemptNumber、webhookTimeout 等。
本地 URL
默认禁止 http://localhost。若开发环境需要，在 config.php：
'webhookAllowedAddressList' => ['localhost:8080'],
调试
- 开启 Espo debug 模式看日志
- 查表
webhook_queue_item、webhook_event_queue_item - 接收端记录 raw body 与 Signature
与应用密钥
对外 API 调用 Espo 用 API User + API Key；Webhook 是 Espo 主动推送。二者配合可实现双向集成。
见 应用密钥。