Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
DDNS Script for Hover (using their unofficial API)
#!/usr/bin/env python
""" Provides dynamic DNS functionality for using their unofficial API.
This script is based off one by Dan Krause:"""
__author__ = "Andrew Barilla"
__credits__ = ["Andrew Barilla", "Dan Krause"]
__license__ = "GPL"
__version__ = "1.0"
__maintainer__ = "Andrew Barilla"
__email__ = ""
__status__ = "Production"
import requests
import json
# Your username and password
username = "username"
password = "password"
# Sign into and then go to:
# Look for the subdomain record that you want to update and put its id here.
dns_id = "dns0000000"
class HoverException(Exception):
class HoverAPI(object):
def __init__(self, username, password):
params = {"username": username, "password": password}
r ="", params=params)
if not r.ok or "hoverauth" not in r.cookies:
raise HoverException(r)
self.cookies = {"hoverauth": r.cookies["hoverauth"]}
def call(self, method, resource, data=None):
url = "{0}".format(resource)
r = requests.request(method, url, data=data, cookies=self.cookies)
if not r.ok:
raise HoverException(r)
if r.content:
body = r.json()
if "succeeded" not in body or body["succeeded"] is not True:
raise HoverException(body)
return body
ip ="")
if ip.ok:
# connect to the API using your account
client = HoverAPI(username, password)
current_ip = ip.content
same_ip = False
current ="get", "dns")
for domain in current.get("domains"):
for entry in domain["entries"]:
if entry["id"] == dns_id and entry["content"] == current_ip:
same_ip = True
if not same_ip:"put", "dns/" + dns_id, {"content": current_ip})
Copy link

heypete commented Sep 10, 2014

Instead of making a relatively heavy TCP+HTTP call to to determine your IP address, considering making a lightweight UDP+DNS call instead.

If you perform a DNS query for the A record of using resolver{1,2}, the result will be your IP address. Note: you need to directly query that server, rather than using your ISP's (or other) resolving nameservers.

The equivalent query using dig would be: "dig +short". I'm not sure how that'd translate to Python, but I'd imagine it's fairly straightforward.

Copy link

icodebot commented Feb 4, 2015

Thanks for this!

Copy link

texasaggie97-zz commented Jan 3, 2018

I have incorporated the functionality of your script into a script that does what yours does, but can also run continuously polling every so often for a change. I also added and simple install script and systemd .service file to allow using it as a service on Linux (at least on Ubuntu)


Copy link

darrenwatt commented Mar 15, 2018

This stopped working recently, I had to update line 38 to post as (application/json)
r ="", json=params)

Copy link

masterrex commented Dec 2, 2018

I can't seem to update records with PUT to api/dns/{id}. I continually get an error: "Can not update attributes: dn"

Has anyone else seen this issue?

Copy link

bkanuka commented Jan 30, 2019

@masterrex yes - but I am unable to fix it. Did you find a way?

Copy link

l0cutis commented May 23, 2019

As the API is entirely un-documented and un-supported, it appears they've made some changes recently :) @masterrex and @bkanuka , this might help?

@heypete - thanks for the OpenDNS trick :)

The API URL for a DNS update now appears to be

and the minimum JSON required to perform an update is

For anyone interested I've pulled this together into a powershell script which will update a single record.
The script demonstrates the bare essentials, nothing clever - but it does what I need it to for now :)

#Update which Hover record?
$dnsID =     "dns12345678"
$dnsdomain = ""
$username = "Username"
$password = "Password"

#Get current public IP (pretty cool little trick, don't adjust this line)
$myIP = Resolve-DnsName -Name -Server

#Connect to HoverAPI
$Headers = @{   "accept"="application/json";
$params = @{    "username"=$username;

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$loginResult = Invoke-WebRequest -Uri "" -Method POST -Body ($params|ConvertTo-Json) -Headers $Headers -SessionVariable WebSession

#Check the login was successful
if($loginResult.Headers.'Set-Cookie' -notmatch "hoverauth" -or $loginResult.StatusDescription -ne "OK")
    Write-Host "There has been a problem"
    #update the record
    $jsonRequest = '{"domain":{"id":"domain-' + $dnsdomain + '","dns_records":[{"id":"'+$dnsID+'"}]},"fields":{"content":"' + $myIP.IPAddress + '"}}'
    $updateResult = Invoke-WebRequest -Uri "" -Method put -Body $jsonRequest -WebSession $WebSession


Copy link

bkanuka commented May 23, 2019

@l0cutis Thank you, but since posting here, I contributed a Hover provider to lexicon. I would now recommend using lexicon for updating Hover. If you do use lexicon and it breaks (because their undocumented API changed) feel free to open a ticket there and tag me.

Copy link

l0cutis commented May 23, 2019

@bkanuka Lexicon would seem to do the job nicely :) Wish I'd noticed it sooner! but then I wouldn't have had the fun of figuring this out. Thanks for the heads up! I'll be sure to point others in that direction in the future :) - and thanks for replying ^.^

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment