Skip to main content
Home
  • API 参考
  • Webhook 事件回调

Webhook 事件回调

Webhook 是 GlobFax 平台提供的实时状态通知机制。当传真任务状态或收件人发送状态发生变更时，系统将主动向开发者预先配置的回调地址推送事件通知，彻底替代轮询查询模式，提升业务处理效率与实时性。

#快速配置流程

  1. 设置回调地址
    登录管理后台，依次进入「开发者」→「API 设置」页面，填写合法公网回调网址，保存配置即可生效。

  2. 查看通知记录
    登录管理后台，依次进入「开发者」→「回调通知」页面，可查阅全部历史推送记录、送达状态与响应详情。

  3. 回调地址约束
    必须为公网可正常访问的 HTTP/HTTPS 链接。地址字符长度上限 255 位。服务端需在 30 秒内完成响应，超时判定推送失败并触发重试。

#回调数据示例

json 
{
  "task_ref": "fax_789xyz",
  "name": "2025年2月客户账单",
  "status": "completed",
  "scheduled_at": "2025-02-22 14:30:00",
  "created_at": "2025-02-22 10:00:00",
  "recipients": [
    {
      "rcpt_ref": "rcpt_111aaa",
      "phone_number": "8613812345678",
      "unit_price": 1.5,
      "page_count": 3,
      "charged_amount": 4.5,
      "status": "success",
      "failed_code": null,
      "failed_reason": null,
      "completed_at": "2025-02-22 14:31:20",
      "created_at": "2025-02-22 10:00:00"
    },
    {
      "rcpt_ref": "rcpt_222bbb",
      "phone_number": "8613912345699",
      "unit_price": 1.5,
      "page_count": 3,
      "charged_amount": null,
      "status": "failed",
      "failed_code": 2003,
      "failed_reason": "busy or unavailable",
      "completed_at": "2025-02-22 14:35:10",
      "created_at": "2025-02-22 10:00:00"
    }
  ]
}

#数据字段说明

#任务基础信息

字段名 数据类型 字段说明 示例值
task_ref string 传真任务唯一标识 fax_789xyz
name string 任务自定义名称 2025年2月客户账单
status string 任务整体状态 completed
scheduled_at string 预约发送时间，无预约则为空 2025-02-22 14:30:00
created_at string 任务创建时间 2025-02-22 10:00:00
recipients array[object] 收件人发送结果明细列表 -

#收件人信息

字段名 数据类型 字段说明 示例值
rcpt_ref string 单收件人唯一标识 rcpt_111aaa
phone_number string 收件人传真号码 8613812345678
unit_price float 单页传真单价（元/页） 1.5
page_count int 传真文档页数 3
charged_amount float 本条扣费总额，失败则为 null 4.5
status string 单收件人发送状态 success
failed_code string 失败错误码，成功则为 null
failed_reason string 失败原因描述，成功则为 null
completed_at string 发送完成时间，未完成则为 null 2025-02-22 14:31:20
created_at string 收件人任务创建时间 2025-02-22 10:00:00

#响应处理与重试

接收推送后，需及时返回对应状态码，系统依据响应结果判定送达状态。为保障推送可靠送达，平台内置指数退避重试策略。

  1. 200 OK：
    判定处理成功，终止本次推送

  2. 4xx / 5xx：
    判定处理异常，触发自动重试机制

  3. 失败重试：
    最大重试次数：5 次
    重试间隔梯度：1 分钟、2 分钟、3 分钟、4 分钟、5 分钟

最佳实践： 核心回执逻辑精简处理，建议 3 秒内返回响应，规避超时。数据存储、统计通知等复杂逻辑延后异步执行。校验报文格式、字段完整性，异常数据丢弃处理。

#常见问题

  1. 同一任务会多次推送通知吗？
    单次状态变更仅推送一次，推送失败会按照规则重试；成功送达后不会重复推送相同状态事件。

  2. 如何修改生效回调地址？
    在 API 设置页面直接更新网址并保存，系统自动验证新地址，旧地址即刻停止接收通知。

  3. 重试推送是否会干扰正常业务？
    采用梯度间隔重试，不会集中请求施压；业务端做好幂等处理即可规避重复操作风险。