回调通知（Webhook）配置指南¶

概述¶

回调通知（Webhook）提供一种实时事件推送机制。当传真任务状态发生变化时，系统会主动向您配置的回调地址发送 HTTP POST 请求，通知您任务的最新状态和详细信息。

使用 Webhook 可以避免频繁轮询 API，实现更高效、实时的状态监控。

API 端点： http://api.globfax.com

快速开始¶

1. 设置回调地址¶

登录 GlobFax 管理后台。
进入「开发者」菜单 → 「API 设置」页面。
在「回调网址（Webhook Url）」字段填写完整的回调地址。
点击保存，完成配置。

回调地址示例：

http://example.com/api/globfax-webhook
https://yourdomain.com/webhook/fax-notifications

2. 查看通知历史¶

进入「开发者」菜单 → 「回调通知」页面，可以查看所有历史通知记录，包括发送状态和响应详情。

回调地址要求

必须是公网可访问的 HTTP/HTTPS 地址。
地址长度不超过 255 个字符。
服务器必须在 30 秒 内返回响应，否则系统会标记为超时并触发重试。

回调通知格式¶

请求方式¶

方法：POST
Content-Type：application/json
字符编码：UTF‑8
超时时间：30 秒

通知数据结构¶

{
  "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": 0.5,
      "page_count": 3,
      "charged_amount": 1.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": "8613912345678",
      "unit_price": 0.5,
      "page_count": 3,
      "charged_amount": 1.5,
      "status": "failed",
      "failed_code": "BUSY",
      "failed_reason": "Recipient line is busy",
      "completed_at": "2025-02-22 14:35:10",
      "created_at": "2025-02-22 10:00:00"
    }
  ]
}

字段说明¶

任务信息¶

字段名	类型	说明
`task_ref`	string	传真任务唯一标识符
`name`	string	任务名称
`status`	string	任务整体状态：`done`（已完成）、`failed`（已失败）
`scheduled_at`	string	预约发送时间（Y‑m‑d H:i:s 格式，未预约则为创建时间）
`created_at`	string	任务创建时间（Y‑m‑d H:i:s 格式）
`recipients`	array[object]	收件人列表，包含所有收件人的详细信息

收件人信息（`recipients` 数组中的对象）¶

字段名	类型	说明
`rcpt_ref`	string	收件人唯一标识符
`phone_number`	string	收件人传真号码
`unit_price`	float	单页发送费用（元/页）
`page_count`	int	实际发送页数
`charged_amount`	float	总费用（unit_price × page_count）
`status`	string	收件人发送状态：`success`（成功）、`failed`（失败）、`canceled`（已取消）
`failed_code`	string	失败代码（仅失败状态有效）
`failed_reason`	string	失败原因描述（仅失败状态有效）
`completed_at`	string	发送完成时间（Y‑m‑d H:i:s 格式，未完成则为 `null`）
`created_at`	string	收件人记录创建时间（Y‑m‑d H:i:s 格式）

状态说明

任务整体状态及收件人发送状态的详细定义，请参考 API 概述中的「状态说明」章节。

处理通知¶

服务器响应要求¶

您的回调服务器接收到通知后，必须返回标准的 HTTP 响应：

响应状态码	系统处理方式
200 OK	通知处理成功，系统标记为已送达
4xx/5xx	通知处理失败，系统会根据重试策略重新发送

响应示例¶

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 23

{"status": "received"}

处理建议¶

快速响应：处理逻辑应尽量简单快速，在 3 秒 内返回响应。
异步处理：如需复杂处理，可先存储通知数据，再异步处理。
幂等性：确保相同通知多次发送不会导致重复处理。
验证数据：检查接收到的数据格式和完整性。

重试机制¶

系统为确保通知可靠送达，内置了以下重试策略：

重试次数：最多 5 次。
重试间隔：指数退避策略，依次为 1、2、3、4、5 分钟。
触发条件：服务器返回 4xx/5xx 状态码，或响应超时（30 秒）。
最终处理：5 次重试均失败后，通知标记为“发送失败”，可在管理后台查看详情。

重试策略详情

关于重试机制的更多说明，请参考 API 概述中的「频率限制与重试」章节。

测试与调试¶

1. 配置测试¶

设置并保存回调地址。
测试通知包含标准的任务数据结构。
确保您的服务器能正确接收并返回 200 响应。

2. 手动测试¶

在「回调通知」页面点击「发送测试通知」按钮。
系统会立即发送一条测试通知到您的回调地址。
观察服务器接收情况和处理结果。

3. 调试建议¶

查看日志：在服务器端记录接收到的原始通知数据。
模拟请求：使用 Postman 等工具模拟 Webhook 请求，测试处理逻辑。
监控响应：确保服务器在 3 秒内返回响应，避免超时。
检查网络：确保回调地址公网可访问，无防火墙限制。

常见问题¶

1. 通知发送频率如何？¶

每个状态变化事件只发送一次通知。
如果发送失败，系统会按重试策略重新发送（最多 5 次）。
成功送达后不再重复发送相同状态的通知。

2. 如何更改回调地址？¶

在「API 设置」页面直接修改回调地址并保存。
修改后，系统会发送测试通知验证新地址。
旧地址将不再接收新通知。

3. 重试机制会影响业务吗？¶

重试机制确保通知的可靠送达。
指数退避策略避免对您的服务器造成压力。
您可以随时在管理后台查看重试状态。

故障排查¶

如果遇到问题，按以下步骤排查：

检查配置：确认回调地址配置正确且可公网访问。
查看日志：检查服务器访问日志，确认是否收到请求。
验证响应：确保服务器返回正确的 HTTP 状态码（200）。
检查网络：确认无防火墙或网络策略限制。
测试连接：使用 curl 或 Postman 手动测试回调地址。

下一步¶

需要配置回调地址？前往「API 设置」页面。
需要查看历史通知？前往「回调通知」页面。
需要 API 集成？参考其他 API 接口文档。
遇到问题？联系技术支持获取帮助。