Webhookit

Lisää päätepiste

Kohdassa Hallintapaneeli → Webhookit, API:n kautta tai pyytämällä tekoälyänne MCP:n välityksellä (create_webhook). Valitse tapahtumatyypit, ryhmät kuten dns.* tai kaikki tapahtumat. Vastaus sisältää allekirjoitussalaisuuden (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-osoitteen on oltava https julkisella palvelimella. Vastaa millä tahansa 2xx-koodilla 10 sekunnin kuluessa; tee hitaat toiminnot vasta vastaamisen jälkeen.

Mitä saatte

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

Tapahtuman id pysyy samana, kun toimitusta yritetään uudelleen tai se lähetetään uudestaan: käyttäkää sitä jo käsiteltyjen tapahtumien ohittamiseen. Tapahtumat voivat saapua väärässä järjestyksessä.

Tarkista allekirjoitus

t on pyynnön Unix-aika, ja v1 on heksamuotoinen HMAC-SHA256-tiiviste, joka lasketaan t:stä, pisteestä ja raa'asta rungosta salaisella avaimellasi. Laske se raaoista tavuista ennen JSONin jäsentämistä, vertaa vakioajassa ja hylkää yli viisi minuuttia vanhat aikaleimat.

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

Uudelleenyritykset ja käytöstä poisto

Toimitusta, johon ei saada vastausta tai joka päättyy aikakatkaisuun, 5xx-, 408- tai 429-koodiin, yritetään uudelleen seuraavin välein: 1m, 5m, 30m, 2h, 5h, 10h, 10h: 8 yritystä noin vuorokauden aikana. Mikä tahansa muu 4xx epäonnistuu heti. Kun 5 peräkkäistä toimitusta on epäonnistunut lopullisesti, päätepiste poistetaan käytöstä ja saatte sähköpostin; ottakaa se uudelleen käyttöön hallintapaneelissa tai komennolla PATCH active: true. Jokainen toimitus tilakoodeineen ja vastauksenne alkuineen näkyy hallintapaneelissa ja osoitteessa GET /api/v1/webhooks/{id}/deliveries, jossa voitte lähettää toimituksen uudelleen.

Tapahtumat

data sisältää verkkotunnuksen tai vyöhykkeen sekä kohteen: tietueen (päivityksissä myös previous), vanhenemispäivän, nimipalvelimet (myös previous). Kunkin kohteen tarkat kentät ovat samat kuin REST API:ssa.

Saapuvat sähköpostit voidaan myös lähettää URL-osoitteeseen: määrittäkää se osoitekohtaisesti kohdassa Sähköpostin edelleenlähetys. Näissä lähetyksissä käytetään samoja otsakkeita ja allekirjoitusta, ja X-NameOcean-Event on email.received.

Hyvä tietää

• NameOcean lähettää vain julkisiin osoitteisiin, jotka tarkistetaan uudelleen jokaisella toimituksella, eikä koskaan seuraa uudelleenohjauksia.
• Vaihtakaa salaisuus hallintapaneelissa, jos se vuotaa; tapahtumat allekirjoitetaan uudella salaisuudella välittömästi.
• Lähetä testi lähettää webhook.test-tapahtuman heti päätepisteen tapahtumasuodattimesta riippumatta.