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 请求体

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 项目首页
• 配置文件格式
• 命令行使用
• 开发者指南