Webhooks

Endpunkt hinzufügen

Unter Dashboard → Webhooks, über die API oder indem Sie Ihre KI per MCP darum bitten (create_webhook). Wählen Sie einzelne Event-Typen, Gruppen wie dns.* oder alle Events. Die Antwort enthält das Signatur-Secret (whsec_…).

$ curl -X POST https://nameocean.net/api/v1/webhooks \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"url": "https://example.com/hooks/nameocean", "events": ["dns.*", "ssl.issued", "domain.expiring"]}'

Die URL muss HTTPS auf einem öffentlichen Server sein. Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status; erledigen Sie langwierige Aufgaben erst nach der Antwort.

Was Sie erhalten

Content-Type: application/json
X-NameOcean-Event: dns.record.created
X-NameOcean-Delivery: whd_7c1e0f9a2b3d4e5f6a7b8c9d
X-NameOcean-Signature: t=1794300000,v1=5f2b…

{
  "id": "evt_3a9f1c2e4b5d6a7c8e9f0a1b",
  "type": "dns.record.created",
  "created": "2026-11-10T09:20:00+00:00",
  "data": {
    "zone": "example.com",
    "record": {"id": 4211, "type": "A", "hostname": "www", "ip": "203.0.113.10", "ttl": "1h"}
  }
}

Die Event-ID bleibt gleich, wenn eine Zustellung wiederholt oder erneut gesendet wird: Nutzen Sie sie, um bereits verarbeitete Events zu überspringen. Events können in beliebiger Reihenfolge eintreffen.

Signatur prüfen

t ist die Unix-Zeit der Anfrage, v1 der hexadezimale HMAC-SHA256 aus t, einem Punkt und dem unveränderten Body, signiert mit Ihrem Secret. Berechnen Sie ihn über die Rohbytes, bevor Sie das JSON parsen, vergleichen Sie in konstanter Zeit und lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind.

t=1794300000,v1=hex(HMAC_SHA256(secret, "1794300000." + raw_body))

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(","))
    ts = int(fields["t"])
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))

import crypto from "node:crypto";

export function verify(secret, header, rawBody, tolerance = 300) {
  const fields = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const ts = Number(fields.t);
  if (Math.abs(Date.now() / 1000 - ts) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  const got = Buffer.from(fields.v1 || "", "hex");
  return got.length === 32 && crypto.timingSafeEqual(Buffer.from(expected, "hex"), got);
}

func Verify(secret, header string, body []byte) bool {
	var ts int64
	var v1 string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(part, "=")
		switch k {
		case "t":
			ts, _ = strconv.ParseInt(v, 10, 64)
		case "v1":
			v1 = v
		}
	}
	if d := time.Now().Unix() - ts; d > 300 || d < -300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(mac, "%d.", ts)
	mac.Write(body)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1))
}

Wiederholungen und Deaktivierung

Eine Zustellung ohne Antwort, mit Timeout, 5xx, 408 oder 429 wird nach 1m, 5m, 30m, 2h, 5h, 10h, 10h wiederholt: 8 Versuche über etwa einen Tag. Jeder andere 4xx-Status schlägt sofort fehl. Wenn 5 Zustellungen in Folge endgültig fehlschlagen, wird der Endpunkt deaktiviert und Sie erhalten eine E-Mail; aktivieren Sie ihn im Dashboard oder mit PATCH active: true wieder. Jede Zustellung wird mit Statuscode und dem Anfang Ihrer Antwort im Dashboard und unter GET /api/v1/webhooks/{id}/deliveries aufgeführt, wo Sie sie erneut senden können.

Ereignisse

data enthält die Domain oder Zone und das Objekt: den Eintrag (bei Änderungen mit previous), das Ablaufdatum, die Nameserver (mit previous). Die genauen Felder jedes Objekts entsprechen denen der REST-API.

Eingehende E-Mails können ebenfalls an eine URL gesendet werden: Legen Sie diese pro Adresse unter E-Mail-Weiterleitung fest. Diese POSTs verwenden dieselben Header und dieselbe Signatur, mit X-NameOcean-Event: email.received.

Gut zu wissen

• NameOcean sendet nur an öffentliche Adressen, prüft dies bei jeder Zustellung erneut und folgt niemals Weiterleitungen.
• Erneuern Sie das Secret im Dashboard, falls es kompromittiert wurde; Events werden sofort mit dem neuen signiert.
• „Test senden“ schickt sofort ein webhook.test-Event, unabhängig vom Event-Filter des Endpunkts.