DDNS/docs/en/providers/callback.md

Callback Provider Configuration Guide

Callback Provider is a universal custom callback interface that allows you to forward DDNS update requests to any custom HTTP API endpoint or webhook. This provider is highly flexible, supporting GET and POST requests with variable substitution functionality.

Return to All Providers to see more options

Basic Configuration

Parameter	Description	Required	Example
id	Callback URL address with variable substitution support	✅	https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__
token	POST request parameters (JSON object or JSON string), empty for GET requests	Optional	{"api_key": "your_key"} or "{\"api_key\": \"your_key\"}"
endpoint	Optional API endpoint address, will not participate in variable substitution	Optional	https://api.example.com/ddns
dns	Fixed value "callback", indicates using callback method	✅	"callback"

Complete Configuration Example

{
    "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
    "dns": "callback",
    "endpoint": "https://api.example.com", // endpoint can be merged with id parameter
    "id": "/ddns?domain=__DOMAIN__&ip=__IP__", // endpoint and id cannot both be empty
    "token": "", // empty string means using GET request, with value uses POST request
    "index4": ["url:http://api.ipify.org", "public"],
    "index6": "public",
    "ipv4": "ddns.newfuture.cc",
    "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"]
}

Parameter Description

Parameter	Description	Type	Range/Options	Default	Parameter Type
index4	IPv4 source	Array	Reference	default	Common Config
index6	IPv6 source	Array	Reference	default	Common Config
ipv4	IPv4 domains	Array	Domain list	None	Common Config
ipv6	IPv6 domains	Array	Domain list	None	Common Config
proxy	Proxy settings	Array	Reference	None	Common Network
ssl	SSL verification	Boolean/String	"auto", true, false	auto	Common Network
cache	Cache settings	Boolean/String	true, false, filepath	true	Common Config
log	Log configuration	Object	Reference	None	Common Config

Request Methods

Method	Condition	Description
GET	token is empty	Use URL query parameters
POST	token is not empty	Use JSON request body

HTTP Responses and Caching

Callback accepts only final HTTP statuses from 200 to 299 as success. Empty response bodies, such as HTTP 204 responses, are allowed. HTTP 404, 429, and all other non-2xx statuses are failures. The current IP is not cached as a successful update, so a later synchronization will retry. Callback does not interpret custom business errors in an HTTP 200 response body. To report an update failure, the callback endpoint should return an appropriate non-2xx HTTP status.

GET Request Example

{
    "$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 Request Example

{
    "$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"
}

Variable Substitution

Callback Provider supports the following built-in variables that are automatically replaced during requests:

Variable	Description	Example Value
__DOMAIN__	Full domain name	sub.example.com
__IP__	IP address (IPv4 or IPv6)	192.168.1.100 or 2001:db8::1
__RECORDTYPE__	DNS record type	A, AAAA, CNAME
__TTL__	Time to live (seconds)	300, 600
__LINE__	Resolution line	default, unicom
__TIMESTAMP__	Current timestamp	1634567890.123

Usage Scenarios

1. Custom Webhook

Send DDNS update notifications to custom webhooks:

{
    "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. Using String Format Token

When you need to dynamically construct complex JSON strings:

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

Troubleshooting

Debugging Methods

1. Enable Debug: Set "debug": true in configuration
2. View Logs: Check detailed information in DDNS runtime logs
3. Test API: Use curl or Postman to test callback API
4. Network Check: Ensure network connectivity and DNS resolution are normal

Testing Tools

You can use online tools to test callback functionality:

# Test GET request using curl
curl "https://httpbin.org/get?domain=test.example.com&ip=192.168.1.1"

# Test POST request using curl
curl -X POST "https://httpbin.org/post" \
  -H "Content-Type: application/json" \
  -d '{"domain": "test.example.com", "ip": "192.168.1.1"}'

Related Links

• DDNS Project Homepage
• Configuration File Format
• Command Line Usage
• Developer Guide