Webhooks

What are webhooks

Webhooks are event-driven HTTP callbacks. When something happens to one of your hosts — an IP change, a new host being created, or a host going offline — NovaDNS sends an HTTP POST request to the URL you registered, containing a JSON payload describing the event.

Unlike polling the API on a timer, webhooks push data to you the moment an event occurs. This makes them ideal for low-latency automation — for example, updating a firewall allowlist within seconds of your home IP changing.

Creating a webhook

Webhooks are managed per workspace from the dashboard.

1. Open the dashboard and navigate to Webhooks in the sidebar.
2. Click New webhook.
3. Enter your endpoint URL. It must be publicly reachable and use https://.
4. Select one or more event types to subscribe to.
5. Save — NovaDNS generates a signing secret for this webhook immediately.

Copy the signing secret now — it is only shown once. You will use it to verify the authenticity of incoming payloads on your server.

Event types

Subscribe to any combination of the following events. You can update your subscriptions at any time from the webhook settings page.

Payload format

Every webhook delivery is an HTTP POST with a Content-Type: application/json body. The top-level event field identifies the event type; remaining fields are event-specific.

{
  "event":     "host.ip_updated",
  "host":      "home.novaip.link",
  "ipv4":      "203.0.113.42",
  "ipv6":      "2001:db8::1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Fields that do not apply to the current state are null — for example, ipv6 is null when the host has no IPv6 address recorded.

The timestamp is always UTC in ISO 8601 format. Use it to detect out-of-order or duplicate deliveries when idempotency matters.

Verifying signatures

Every request includes an X-NovaDNS-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook's secret. Always verify this signature before processing the payload to ensure the request genuinely came from NovaDNS and has not been tampered with.

import crypto from "node:crypto"

// Use a raw body parser — signature is over the raw bytes
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const secret    = process.env.NOVADNS_WEBHOOK_SECRET
  const signature = req.headers["x-novadns-signature"]

  const expected  = crypto
    .createHmac("sha256", secret)
    .update(req.body)
    .digest("hex")

  if (!crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )) {
    return res.status(401).send("Invalid signature")
  }

  const payload = JSON.parse(req.body)
  // handle payload.event …
  res.status(200).send()
})

Security tips

• Always verify the X-NovaDNS-Signature header before trusting the payload.
• Only accept deliveries over HTTPS — never plain HTTP endpoints.
• Rotate your webhook secret periodically from the webhook settings page; NovaDNS immediately begins signing with the new secret.
• Respond with a 2xx status as quickly as possible — do heavy processing asynchronously to avoid delivery timeouts.
• Use the timestamp field to deduplicate retried deliveries if your handler is not idempotent.
• Restrict your endpoint to NovaDNS IP ranges if your infrastructure supports allowlisting (ranges published at novadns.io/ips).

Team webhooks

Webhooks are scoped to a workspace — personal webhooks fire only for hosts in your personal workspace, and team webhooks fire only for hosts belonging to that team. When you switch workspaces in the dashboard, the Webhooks section shows only the webhooks for the active workspace.

Within a team, only members with the Owner or Admin role can create, edit, or delete webhooks. Members with the Member role can view registered webhook endpoints but cannot modify them.