Webhooks#

Dos tipos de webhooks conectan su aplicación con NAMES LEGAL:

site.ready#

Se envía a la dirección de notificación de su canal de venta cuando un sitio comprado a través de su canal está pagado y listo para usarse.

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 es el data-ref que usted pasó al marco de compra: úselo para encontrar a su usuario.

Verificar la firma#

La firma es un HMAC-SHA256 del cuerpo en bruto con el secreto de firma de su canal. Verifíquela siempre antes de confiar en el mensaje.

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

Entrega#

• Responda con cualquier estado 2xx dentro de 10 segundos.
• En caso de fallo, la entrega se reintenta con retrasos crecientes (de un minuto hasta una hora) durante varias horas.
• El mismo evento puede llegar excepcionalmente dos veces: haga que su gestor sea idempotente, por ejemplo usando site_url.

Webhook entrante del conector#

Cuando un propietario de sitio conecta su API como fuente de datos, su consola muestra una dirección de webhook única para esa conexión:

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

Llámela con un POST vacío cada vez que sus datos cambien:

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

• La respuesta es 202 Accepted; la sincronización se ejecuta en segundo plano en menos de un minuto.
• Las llamadas en ráfaga se fusionan: como máximo una sincronización por minuto y por conexión.
• El token es el secreto. El propietario del sitio puede reemplazarlo desde la consola en cualquier momento; la dirección antigua entonces responde 404.