Webhook 是在贵公司发生某事时,我们 POST 到您应用地址的一条消息,这样另一个应用就无需反复查询。
-
第 1 步: 添加端点
在 管理 → 设置 → API 与 Webhook 的 Webhook 下,点击 添加端点。
-
第 2 步: 输入地址
填写 端点 URL(必须是公开的 https:// 地址)和可选的 描述。
-
第 3 步: 选择事件
在 事件 下,勾选您需要的事件,或勾选 所有事件,包括以后新增的事件。
-
第 4 步: 复制签名密钥
保存后,签名密钥 只会显示一次。将其复制到接收应用中,以便其验证每条消息确实来自我们。
-
第 5 步: 进行测试
点击 发送测试事件,并检查 投递日志。
可用事件
- 联系人:联系人已创建或更新。
- 发票:已开具、已全额付款、已作废。报价单:已接受。
- 收付款:付款或收款已过账。
- 账单:已收到(已过账)、已全额付款。费用:已记录一笔费用。
- 库存:某项商品降至或低于其再订购水平。
- 假期:已创建一份请假申请。
投递与重试
- 您的应用应在 10 秒内以 2xx 状态码响应。其他任何情况均视为失败。
- 失败的投递会自动重试,在数小时内最多尝试六次,每次等待时间都会更长。
- 使用 管理 打开端点,即可查看 投递日志:每个事件及其 负载、您服务器的 响应 以及状态:已交付、失败 或 待处理。点击 重新发送 可再次发送。
- 取消勾选 向此端点发送事件 可暂停该端点,或点击 移除 将其删除。长时间持续失败的端点会被自动关闭。
验证签名
每次投递都带有请求头 X-Webhook-Signature: t=<timestamp>,v1=<signature>。使用您的签名密钥计算“<timestamp>.<raw body>”的 HMAC-SHA256,并与 v1 进行比较;拒绝超过 5 分钟的时间戳。X-Webhook-Id 在重试之间保持不变,因此可用它忽略重复消息。