Webhooks#

Dois tipos de webhooks ligam a sua aplicação ao NAMES LEGAL:

site.ready#

Enviado para o endereço de notificação do canal de venda quando um site comprado através desse canal é pago e fica pronto a utilizar.

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 é o data-ref passado à moldura de compra: utilize-o para encontrar o utilizador.

Verificar a assinatura#

A assinatura é um HMAC-SHA256 do corpo em bruto com o segredo de assinatura do canal. Verifique-a sempre antes de confiar na mensagem.

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 com qualquer estado 2xx dentro de 10 segundos.
• Em caso de falha, a entrega é repetida com atrasos crescentes (de um minuto até uma hora) durante várias horas.
• O mesmo evento pode, excecionalmente, chegar duas vezes: torne o processador idempotente, por exemplo com base em site_url.

Webhook de entrada do conector#

Quando um proprietário de site liga uma API como fonte de dados, a consola mostra um endereço de webhook exclusivo para essa ligação:

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

Chame-o com um POST vazio sempre que os dados mudarem:

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

• A resposta é 202 Accepted; a sincronização é executada em segundo plano dentro de um minuto.
• As chamadas em rajada são fundidas: no máximo uma sincronização por minuto e por ligação.
• O token é o segredo. O proprietário do site pode substituí-lo a partir da consola a qualquer momento; o endereço antigo passa então a responder 404.