The CitationLab package for Umbraco

Requirements

Check these before you install.

• Umbraco 13 LTS on .NET 8

  This is the version the package targets.

• Umbraco 14 and later: not yet

  Umbraco 14 changed how backoffice extensions are built, so the dashboard has to be rewritten before the package supports it. The API side is not affected by that change.

• Outbound HTTPS

  The web server must be able to reach manager.citationlab.ai over HTTPS, or pairing fails.

• An admin user

  Pairing and the feature switches live in a dashboard only users in Umbraco's admin group can see.

1. Install

Add the package to the project that runs your Umbraco site.

1. 1

   Add the package

   From the folder of your Umbraco web project, run dotnet add package CitationLab.Umbraco.

2. 2

   Rebuild

   Build the solution the way you normally do and deploy it.

3. 3

   Restart the site

   On start-up the package creates its own database tables. No content or template is touched.

Optional configuration

You only need configuration to point the package at a different Manager, such as a staging environment. Without it, the package talks to manager.citationlab.ai.

{
  "CitationLab": {
    "ManagerUrl": "https://manager.citationlab.ai"
  }
}

Errors from the package are written to the normal Umbraco log with the prefix [citationlab], so you can filter for them.

2. Pair with AI Marketing Manager

Pairing gives the site a permanent API key and tells Manager where the site lives. It takes a token from Manager and one click in the Umbraco backoffice.

1. 1

   Generate a pairing token in Manager

   In AI Marketing Manager, open the project and go to Integrations → Umbraco → Connect, then choose “Generate pairing token”.

2. 2

   Open the CitationLab dashboard

   Sign in to the Umbraco backoffice as an admin, open the Content section and select the “CitationLab” dashboard.

3. 3

   Paste the token and click “Pair”

   The site sends the token, its own URL and basic site information to Manager, and receives its API key in return. The dashboard then shows the site as connected.

• A token works once and expires after 15 minutes. If it runs out, generate a new one.
• Pair from the backoffice on your public hostname. Manager stores the address you were on when you clicked Pair, so pairing from localhost or an internal name leaves Manager with an address it cannot use.
• Pairing needs a backoffice login on purpose: it decides who may read and write the whole site, so knowing the site's URL is not enough.
• One Umbraco site per project. Pairing a project that is already connected replaces the URL and key of that connection.
• To disconnect, use “Disconnect” in the dashboard, which removes the key stored on the site, or remove the connection in Manager, which deletes the connection and Manager's cached copy of your content. Removing it in Manager does not change anything on the Umbraco site.

3. Choose what the package does

Installing the package changes no page on your site. Only the sync group is on from the start, so Manager can read your content. Everything that would change your HTML, handle requests or collect visitor data stays off until you turn it on.

Where to switch features

An admin turns features on and off under Features in the CitationLab dashboard. Developers can do the same through the API with PUT features. Manager reads what is switched on through GET capabilities, which reports both what the installation can do and what is enabled. A call to a feature that is off answers 403 with the code feature_disabled.

4. API reference

The package serves a REST API from your own Umbraco site. This is the API Manager uses after pairing, and your developers can use it too. It is separate from Manager's own REST API, which is described under Resources → API.

Base URL

Every route sits under this path on your site's own domain:

Authentication

• Send the key from pairing as a bearer token: Authorization: Bearer cl_um_… The key is cl_um_ followed by 40 hexadecimal characters.
• GET health is public and needs no key.
• The pairing routes (pair, pairing-status, disconnect) do not accept the key. They need a signed-in backoffice session.

Conventions

• Query parameters are snake_case: per_page, document_type_alias, parent_id, order_by, include_properties.
• Request and response bodies are JSON in camelCase.
• Lists are paged and return items, total, page, perPage and totalPages. per_page defaults to 100 and is capped at 500.
• Content reads and writes take an optional culture parameter. One culture can be published on its own with POST content/{id}/translations/{culture}/publish.
• A node's {id} is its GUID key or its numeric id.

Errors

Every error has the same shape: error is a readable message, code is one of the values below, and details is present when there is more to say.

HTTP/1.1 403 Forbidden

{
  "error": "Feature 'redirects' is disabled on this site",
  "code": "feature_disabled",
  "details": { "feature": "redirects" }
}

Endpoints

The main routes in each group, relative to the base URL. Each group also lists further resources it contains.

Umbraco Forms and Umbraco Commerce are read through a bridge that looks for them at runtime, so the package installs and runs on sites that do not have those licences. The routes then answer with unsupported.

Files served from the site root

With the matching page-output switches on, the package also answers these addresses on your domain:

/robots.txt/sitemap.xml/llms.txt/llms-full.txt/ai.json/.well-known/ai.json/ai-info

Examples

curl https://your-site.example/umbraco/citationlab/v1/capabilities \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY"

curl "https://your-site.example/umbraco/citationlab/v1/content?page=2&per_page=50&status=published&culture=en-US" \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY"

{
  "items": [ … ],
  "total": 412,
  "page": 2,
  "perPage": 50,
  "totalPages": 9
}

curl -X PUT "https://your-site.example/umbraco/citationlab/v1/seo-meta/NODE_KEY?culture=en-US" \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Plumbing services in Oslo",
    "description": "Emergency and planned plumbing, 24/7.",
    "canonical": "https://your-site.example/services/plumbing/",
    "noindex": false
  }'

5. Webhooks

The package can send a signed notification to an HTTPS endpoint you choose whenever content or media changes: your own service, or an automation tool such as Zapier, Make or n8n.

1. 1

   Turn on the webhooks switch

   The webhooks feature is off by default.

2. 2

   Set the receiver

   PUT settings/webhook with a url (http or https) and a secret. GET settings/webhook shows the url and hasSecret, never the secret itself.

3. 3

   Send a test

   POST settings/webhook/test delivers a signed test event so you can check the receiver before a real change.

Nothing is sent until the switch is on and both a url and a secret are set. Pairing already points the webhook at CitationLab Manager with its own secret, so turning the switch on is enough for Manager to see a published change within seconds. Set your own receiver and Manager leaves it in place.

curl -X PUT https://your-site.example/umbraco/citationlab/v1/settings/webhook \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/umbraco", "secret": "a-long-random-string" }'

Events

What a delivery looks like

A JSON POST with event, siteUrl, timestamp (Unix seconds) and data. Fields that are null are left out. X-CL-Event repeats the event name, and X-CL-Signature carries the signature.

POST /umbraco HTTP/1.1
Host: hooks.example.com
Content-Type: application/json; charset=utf-8
X-CL-Event: content.published
X-CL-Signature: 3f1c…e9a0

{
  "event": "content.published",
  "siteUrl": "https://your-site.example",
  "timestamp": 1760000000,
  "data": { "id": "NODE_KEY", … }
}

Verify the signature

X-CL-Signature is the HMAC-SHA256 of the exact raw request body, keyed with your secret, as lowercase hex. Compute it over the raw bytes before you parse the JSON, and compare with a constant-time function. Re-serialising the parsed body changes the bytes and the check fails.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.CL_WEBHOOK_SECRET;

// Keep the raw bytes: the signature covers the body exactly as sent.
app.post("/umbraco", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-CL-Signature") ?? "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const payload = JSON.parse(req.body.toString("utf8"));
  console.log(req.get("X-CL-Event"), payload.data);
  res.sendStatus(204);
});

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

app.MapPost("/umbraco", async (HttpRequest request, IConfiguration config) =>
{
    // Keep the raw bytes: the signature covers the body exactly as sent.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var body = buffer.ToArray();

    var key = Encoding.UTF8.GetBytes(config["CitationLab:WebhookSecret"]!);
    var expected = Convert.ToHexString(HMACSHA256.HashData(key, body)).ToLowerInvariant();
    var received = request.Headers["X-CL-Signature"].ToString();

    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(received)))
        return Results.Unauthorized();

    using var payload = JsonDocument.Parse(body);
    return Results.NoContent();
});

Delivery and retries

• Deliveries are queued and sent outside the save. Saving in the backoffice never waits for your receiver.
• Any status below 400 counts as delivered.
• After a network error, a timeout, a 5xx, 408 or 429, the package tries twice more: after 1 second and after 3 seconds. Other 4xx answers are not retried.
• When all three attempts fail, the package gives up and writes a [citationlab] warning to the Umbraco log. Use the event as a signal to fetch the current state from the API, not as the only copy of the change.

Security and privacy

• Pairing needs a backoffice login

  Only an admin signed in to your backoffice can pair a site. A URL alone cannot connect anything.

• Where the key lives

  On the site, the key is stored in App_Data/CitationLab/apikey.json. Treat that file like a password and keep App_Data out of source control. Manager stores its copy encrypted.

• Opt-in by default

  Only reading is on after install. Page output, request handling, visitor data and integrations each need a deliberate switch.

• No raw IP addresses

  When tracking is on, the package never stores a visitor's raw IP address.

• Every write is logged

  The package keeps its own audit log of every change made through it, with the previous value, and a change can be rolled back. Changes made from Manager are logged in Manager as well.

• Secrets stay put

  The webhook secret is write-only through the API: reads return hasSecret, never the value.

Troubleshooting

Frequently asked questions