Webhooks

Προσθήκη endpoint

Στο Πίνακας ελέγχου → Webhooks, μέσω του API ή ζητώντας το από το AI σας μέσω MCP (create_webhook). Επιλέξτε τύπους συμβάντων, ομάδες όπως dns.* ή όλα τα συμβάντα. Η απάντηση περιλαμβάνει το μυστικό υπογραφής (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"]}'

Η διεύθυνση URL πρέπει να είναι https σε δημόσιο διακομιστή. Απαντήστε με οποιονδήποτε κωδικό 2xx εντός 10 δευτερολέπτων· κάντε τις χρονοβόρες εργασίες αφού απαντήσετε.

Τι λαμβάνετε

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

Το id του συμβάντος παραμένει ίδιο όταν μια αποστολή επαναλαμβάνεται ή στέλνεται ξανά: χρησιμοποιήστε το για να παραλείπετε συμβάντα που έχετε ήδη χειριστεί. Τα συμβάντα μπορεί να φτάσουν εκτός σειράς.

Επαλήθευση της υπογραφής

Το t είναι ο χρόνος Unix του αιτήματος και το v1 είναι το δεκαεξαδικό HMAC-SHA256 του t, μιας τελείας και του ακατέργαστου σώματος, με κλειδί το μυστικό σας. Υπολογίστε το πάνω στα ακατέργαστα bytes, πριν από την ανάλυση του JSON, κάντε τη σύγκριση σε σταθερό χρόνο και απορρίψτε χρονοσφραγίδες παλαιότερες των πέντε λεπτών.

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))
}

Επαναλήψεις και απενεργοποίηση

Μια αποστολή που δεν λαμβάνει απάντηση, λήγει το χρονικό της όριο ή επιστρέφει 5xx, 408 ή 429 επαναλαμβάνεται μετά από 1m, 5m, 30m, 2h, 5h, 10h, 10h: 8 προσπάθειες σε περίπου μία ημέρα. Οποιοσδήποτε άλλος κωδικός 4xx αποτυγχάνει αμέσως. Όταν 5 διαδοχικές αποστολές αποτύχουν οριστικά, το endpoint απενεργοποιείται και λαμβάνετε email· ενεργοποιήστε το ξανά από τον πίνακα ελέγχου ή με PATCH active: true. Κάθε αποστολή, με τον κωδικό κατάστασης και την αρχή της απάντησής σας, εμφανίζεται στον πίνακα ελέγχου και στο GET /api/v1/webhooks/{id}/deliveries, όπου μπορείτε να την στείλετε ξανά.

Συμβάντα

Το data περιέχει το domain ή τη ζώνη και το αντικείμενο: την εγγραφή (με previous στις ενημερώσεις), την ημερομηνία λήξης, τους nameservers (με previous). Τα ακριβή πεδία κάθε αντικειμένου είναι εκείνα του REST API.

Τα εισερχόμενα email μπορούν επίσης να αποστέλλονται σε μια URL: ορίστε την ανά διεύθυνση στην Προώθηση email. Αυτές οι αποστολές χρησιμοποιούν τις ίδιες κεφαλίδες και υπογραφή, με X-NameOcean-Event: email.received.

Καλό να γνωρίζετε

• Το NameOcean στέλνει μόνο σε δημόσιες διευθύνσεις, που ελέγχονται ξανά σε κάθε αποστολή, και δεν ακολουθεί ποτέ ανακατευθύνσεις.
• Αλλάξτε το μυστικό από τον πίνακα ελέγχου αν διαρρεύσει· τα συμβάντα υπογράφονται αμέσως με το νέο.
• Η Αποστολή δοκιμής στέλνει αμέσως ένα συμβάν webhook.test, ανεξάρτητα από το φίλτρο συμβάντων του endpoint.