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

Webhook 事件回调

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

#配置说明

  • 配置途径： 登录 GlobFax 管理后台，进入「开发者」-「Webhook 配置」，填写接收回调地址并保存
  • 生效规则： 保存后立即生效，无需额外操作
  • 安全建议： 我方仅支持 HTTP/HTTPS 公网可访问地址，强烈建议使用 HTTPS 协议，保障数据传输安全

#通知机制

  • 失败重试： 单次推送失败后，系统将在 30 分钟内每 5 分钟自动重试一次，共计 6 次机会
  • 幂等性保障： 每次推送均携带唯一消息 ID，建议接收端以此 ID 作为幂等键，防止重复处理
  • 时间字段格式： 所有时间字段统一使用 UTC 时区，接收端需自行转换为本地时间

#通知事件类型

事件类型 推送时机 通知内容
fax.task.status.changed 传真任务状态变更 任务整体状态、收件人明细
fax.recipient.status.changed 单个收件人发送状态变更 收件人发送结果、计费详情

#通知内容示例

#传真任务状态变更通知

json 
{
  "event": "fax.task.status.changed",
  "message_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "task_ref": "fax_789xyz",
    "name": "2025年2月客户账单",
    "status": "completed",
    "scheduled_at": null,
    "created_at": "2025-02-22T10:00:00Z",
    "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-22T14:31:20Z",
        "created_at": "2025-02-22T10:00:00Z"
      },
      {
        "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-22T14:35:10Z",
        "created_at": "2025-02-22T10:00:00Z"
      }
    ]
  }
}

#收件人状态变更通知

json 
{
  "event": "fax.recipient.status.changed",
  "message_id": "evt_661f9511-f30c-52e5-b827-557766551111",
  "data": {
    "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-22T14:31:20Z",
    "created_at": "2025-02-22T10:00:00Z"
  }
}