Webhooks#

Zwei Arten von Webhooks verbinden Ihre Anwendung mit NAMES LEGAL:

site.ready#

Wird an die Benachrichtigungsadresse Ihres Vertriebskanals gesendet, wenn eine über Ihren Kanal gekaufte Website bezahlt und einsatzbereit ist.

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 ist der data-ref, den Sie dem Kauffenster übergeben haben: Verwenden Sie ihn, um Ihren Nutzer zu finden.

Die Signatur überprüfen#

Die Signatur ist ein HMAC-SHA256 des rohen Bodys mit dem Signaturschlüssel Ihres Kanals. Prüfen Sie sie immer, bevor Sie der Nachricht vertrauen.

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

Zustellung#

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status.
• Bei einem Fehlschlag wird die Zustellung mit wachsenden Verzögerungen (von einer Minute bis zu einer Stunde) über mehrere Stunden hinweg wiederholt.
• Dasselbe Ereignis kann ausnahmsweise zweimal eintreffen: Gestalten Sie Ihren Handler idempotent, zum Beispiel über site_url.

Eingehender Webhook des Konnektors#

Wenn ein Website-Inhaber Ihre API als Datenquelle verbindet, zeigt seine Konsole eine Webhook-Adresse, die für diese Verbindung eindeutig ist:

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

Rufen Sie sie mit einem leeren POST auf, sobald sich Ihre Daten ändern:

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

• Die Antwort lautet 202 Accepted; die Synchronisierung läuft innerhalb einer Minute im Hintergrund.
• In Stößen eintreffende Aufrufe werden zusammengeführt: höchstens eine Synchronisierung pro Minute und Verbindung.
• Das Token ist das Geheimnis. Der Website-Inhaber kann es jederzeit über die Konsole ersetzen; die alte Adresse antwortet dann mit 404.