DDNS/docs/providers/callback.md

Callback Provider 配置指南

Callback Provider 是一个通用的自定义回调接口，允许您将 DDNS 更新请求转发到任何自定义的 HTTP API 端点或者webhook。这个 Provider 非常灵活，支持 GET 和 POST 请求，并提供变量替换功能。

返回 所有服务商 查看更多选项

基本配置

参数	说明	必填	示例
id	回调URL地址，支持变量替换	-	https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__
token	POST 请求参数（JSON对象或JSON字符串），为空时使用GET请求	可选	{"api_key": "your_key"} 或 "{\"api_key\": \"your_key\"}"
endpoint	可选，API端点地址，不会参与变量替换	-	https://api.example.com/ddns
dns	固定值 "callback"，表示使用回调方式	✅	"callback"

完整配置示例

{
    "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
    "dns": "callback",
    "endpoint": "https://api.example.com", // endpoint 可以和 Id 参数合并
    "id": "/ddns?domain=__DOMAIN__&ip=__IP__", //  endpoint 可以和 Id 不能同时为空
    "token": "", // 空字符串表示使用 GET 请求， 有值时使用 POST 请求
    "index4": ["url:http://api.ipify.org", "public"],
    "index6": "public",
    "ipv4": "ddns.newfuture.cc",
    "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"]
}

参数说明

参数	说明	类型	取值范围/选项	默认值	参数类型
index4	IPv4 来源	数组	参考配置	default	公用配置
index6	IPv6 来源	数组	参考配置	default	公用配置
ipv4	IPv4 域名	数组	域名列表	无	公用配置
ipv6	IPv6 域名	数组	域名列表	无	公用配置
proxy	代理设置	数组	参考配置	无	公用网络
ssl	SSL 验证方式	布尔/字符串	"auto"、true、false	auto	公用网络
cache	缓存设置	布尔/字符串	true、false、filepath	true	公用配置
log	日志配置	对象	参考配置	无	公用配置

请求方式

方法	条件	描述
GET	token 为空	使用 URL 查询参数
POST	token 非空	使用 JSON 请求体

HTTP 响应与缓存

Callback 仅将最终 HTTP 状态为 200–299 的响应视为成功，允许响应体为空，例如 HTTP 204。 HTTP 404、429 及其他非 2xx 状态均视为失败，不会将本次 IP 写入成功缓存，后续同步仍会重试。 Callback 不解析 HTTP 200 响应体中的自定义业务错误；如需报告更新失败，请让回调接口返回适当的非 2xx HTTP 状态。

GET 请求示例

{
    "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
    "dns": "callback",
    "id": "https://api.example.com/update?domain=__DOMAIN__&ip=__IP__&type=__RECORDTYPE__",
    "index4": ["url:http://api.ipify.org", "public"],
    "ipv4": "ddns.newfuture.cc",
}

GET https://api.example.com/update?domain=ddns.newfuture.cc&ip=192.168.1.100&type=A

POST 请求示例

{
    "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
    "dns": "callback",
    "endpoint": "https://api.example.com",
    "token": {
        "api_key": "your_secret_key",
        "domain": "__DOMAIN__",
        "value": "__IP__"
    },
    "index4": ["url:http://api.ipify.org", "public"],
    "ipv4": "ddns.newfuture.cc",
}

POST https://api.example.com
Content-Type: application/json

{
  "api_key": "your_secret_key",
  "domain": "ddns.newfuture.cc",
  "value": "192.168.1.100",
}

变量替换

Callback Provider 支持以下内置变量，在请求时会自动替换：

变量	说明	示例值
__DOMAIN__	完整域名	sub.example.com
__IP__	IP地址（IPv4或IPv6）	192.168.1.100 或 2001:db8::1
__RECORDTYPE__	DNS记录类型	A、AAAA、CNAME
__TTL__	生存时间（秒）	300、600
__LINE__	解析线路	default、unicom
__TIMESTAMP__	当前时间戳	1634567890.123

使用场景

1. 自定义 Webhook

将 DDNS 更新通知发送到自定义 webhook：

{
    "endpoint": "https://hooks.example.com",
    "id":"/webhook",
    "token": {
        "event": "ddns_update",
        "domain": "__DOMAIN__",
        "new_ip": "__IP__",
        "record_type": "__RECORDTYPE__",
        "timestamp": "__TIMESTAMP__"
    },
    "dns": "callback",
    "index4": ["default"]
}

2. 使用字符串格式的 token

当需要动态构造复杂的 JSON 字符串时：

{
    "id": "https://api.example.com/ddns",
    "token": "{\"auth\": \"your_key\", \"record\": {\"name\": \"__DOMAIN__\", \"value\": \"__IP__\", \"type\": \"__RECORDTYPE__\"}}",
    "dns": "callback"
}

故障排除

调试方法

1. 启用调试: 在配置中设置 "debug": true
2. 查看日志: 检查DDNS运行日志中的详细信息
3. 测试API: 使用curl或Postman测试回调API
4. 网络检查: 确保网络连通性和DNS解析正常

测试工具

可以使用在线工具测试回调功能：

# 使用 curl 测试 GET 请求
curl "https://httpbin.org/get?domain=test.example.com&ip=192.168.1.1"

# 使用 curl 测试 POST 请求
curl -X POST "https://httpbin.org/post" \
  -H "Content-Type: application/json" \
  -d '{"domain": "test.example.com", "ip": "192.168.1.1"}'

相关链接

• DDNS 项目首页
• 配置文件格式
• 命令行使用
• 开发者指南