Webhook#

Due tipi di webhook collegano la Sua applicazione a NAMES LEGAL:

site.ready#

Inviato all'indirizzo di notifica del Suo canale di vendita quando un sito acquistato tramite il Suo canale è pagato e pronto all'uso.

POST /hooks/names-legal HTTP/1.1
Host: app.example.com
Content-Type: application/json
X-NamesLegal-Signature: sha256=5d41402abc4b2a76b9719d911017c592...

{
  "event": "site.ready",
  "channel": "app-ecole",
  "reference": "instance-42",
  "site_url": "https://ecolehorizon.names.legal",
  "console_url": "https://ecolehorizon.names.legal/cms/",
  "name": "École Horizon",
  "email": "direction@ecole.ch",
  "created_at": "2026-09-24T14:02:11+00:00"
}

reference è il data-ref che Lei ha passato al riquadro di acquisto: lo utilizzi per identificare il Suo utente.

Verifica della firma#

La firma è un HMAC-SHA256 del corpo grezzo con la chiave di firma del Suo canale. La verifichi sempre prima di considerare attendibile il messaggio.

Python

import hashlib, hmac

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Node.js

const crypto = require("crypto");

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return header && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

PHP

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_NAMESLEGAL_SIGNATURE'] ?? '');

Consegna#

• Risponda con uno stato 2xx qualsiasi entro 10 secondi.
• In caso di errore, la consegna viene ritentata con ritardi crescenti (da un minuto fino a un'ora) per diverse ore.
• Lo stesso evento potrebbe eccezionalmente arrivare due volte: renda il Suo gestore idempotente, ad esempio su site_url.

Webhook in ingresso del connettore#

Quando un titolare di sito collega la Sua API come fonte dati, la propria console mostra un indirizzo webhook univoco per quella connessione:

https://<site>/connectors/hook/<id>/<token>/

Lo chiami con un POST vuoto ogni volta che i Suoi dati cambiano:

curl -X POST "https://ecolehorizon.names.legal/connectors/hook/12/Qm9...Zg/"

• La risposta è 202 Accepted; la sincronizzazione viene eseguita in background entro un minuto.
• Le chiamate in rapida successione vengono unite: al massimo una sincronizzazione al minuto per connessione.
• Il token è il segreto. Il titolare del sito può sostituirlo dalla console in qualsiasi momento; il vecchio indirizzo risponde quindi 404.