Webhooks#

Deux types de webhooks relient votre application à NAMES LEGAL :

site.ready#

Envoyé à l'adresse de notification de votre canal de vente lorsqu'un site acheté via votre canal est payé et prêt à l'emploi.

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 correspond au data-ref que vous avez transmis au cadre d'achat : utilisez-le pour retrouver votre utilisateur.

Vérifier la signature#

La signature est un HMAC-SHA256 du corps brut avec le secret de signature de votre canal. Vérifiez-la toujours avant de faire confiance au message.

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'] ?? '');

Livraison#

• Répondez avec un statut 2xx, quel qu'il soit, dans les 10 secondes.
• En cas d'échec, la livraison est retentée avec des délais croissants (d'une minute jusqu'à une heure) pendant plusieurs heures.
• Le même événement peut exceptionnellement arriver deux fois : rendez votre gestionnaire idempotent, par exemple sur site_url.

Webhook entrant du connecteur#

Lorsqu'un propriétaire de site connecte votre API comme source de données, sa console affiche une adresse de webhook unique à cette connexion :

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

Appelez-la avec un POST vide chaque fois que vos données changent :

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

• La réponse est 202 Accepted ; la synchronisation s'exécute en arrière-plan en moins d'une minute.
• Les appels en rafale sont fusionnés : au maximum une synchronisation par minute et par connexion.
• Le jeton est le secret. Le propriétaire du site peut le remplacer depuis la console à tout moment ; l'ancienne adresse répond alors 404.