Webhooks plugin

An administrator registers an endpoint — a URL, a secret the CMS mints, and three filters. When a matching entry changes, the CMS POSTs a signed JSON payload to it. Every attempt is logged and retried on a fixed ladder.

The payload carries references, not content. Read the record back through the public API with your own token, so segment and visibility rules still apply.

Install and register

npm install @orthacms/webhooks-server @orthacms/webhooks-admin

Both ship in every generated app.

// apps/server/src/plugins.ts — after ContentPlugin
import { WebhooksPlugin } from '@orthacms/webhooks-server';

WebhooksPlugin(config.plugins.webhooks);

// apps/admin/src/plugins.ts
import { WebhooksPlugin } from '@orthacms/webhooks-admin';

WebhooksPlugin();

Tables: webhook_endpoints, webhook_endpoint_workspaces, webhook_deliveries (migrations under __drizzle_migrations_webhooks).

Configuration

apps/server/config/webhooks.ts reads five variables:

WEBHOOKS_DELIVERY_INTERVAL=2000        # ms between worker ticks
WEBHOOKS_TIMEOUT=10000                 # per-request timeout, ms
WEBHOOKS_RETENTION_DAYS=30             # how long finished deliveries stay in the log
WEBHOOKS_ALLOW_INSECURE_URLS=false     # permit http://
WEBHOOKS_ALLOW_PRIVATE_NETWORKS=false  # permit loopback, link-local, RFC 1918

The three numbers must be positive — 0 fails the boot. To use a 0 option, set it in config/webhooks.ts directly.

All plugin options:

Events

GET /api/webhook-events returns the catalogue the running server knows.

Creating an endpoint

Usually in the admin (Webhooks → New webhook). The same route with an administrator’s session:

# cookies.txt holds an admin session from POST /api/auth/login
curl -b cookies.txt https://cms.example.com/api/webhooks \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Rebuild site",
        "url": "https://hooks.example.com/orthacms",
        "eventKinds": ["entry.published", "entry.unpublished", "entry.deleted"],
        "contentTypes": ["article"],
        "workspaceIds": ["6b1f0c2e-8a4d-4f7b-9c3e-2d5a7e9f1b40"],
        "headers": { "Authorization": "Bearer receiver-secret" }
      }'
# → 201 { "endpoint": { "id": "…", "secretHint": "x9Qa", … }, "secret": "whsec_…" }

An event is delivered when it matches all three sets. An entry with no workspace reaches only allWorkspaces endpoints.

The secret (whsec_ + 32 random bytes, base64url) is returned by create and rotate only. Everything else shows secretHint, its last four characters.

What the receiver gets

POST /orthacms HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Orthacms-Webhooks/1
Authorization: Bearer receiver-secret
X-Orthacms-Event: entry.published
X-Orthacms-Delivery: 0f1c9a2e-6d3b-4a8e-b5f1-2c7e9d4a1b36
X-Orthacms-Event-Id: 9c41d3b8-2e5f-4b7a-8c19-6d0e3f2a5b74
X-Orthacms-Workspace: 6b1f0c2e-8a4d-4f7b-9c3e-2d5a7e9f1b40
X-Orthacms-Attempt: 1
X-Orthacms-Signature: t=1788689524,v1=5d2f8c…

{
    "id": "0f1c9a2e-6d3b-4a8e-b5f1-2c7e9d4a1b36",
    "event": "entry.published",
    "eventId": "9c41d3b8-2e5f-4b7a-8c19-6d0e3f2a5b74",
    "occurredAt": "2026-09-06T10:12:04.881Z",
    "workspaceId": "6b1f0c2e-8a4d-4f7b-9c3e-2d5a7e9f1b40",
    "actor": { "id": "d0a2c7e1-4f8b-4c3a-9e62-1b5d7f0a3c98", "email": "editor@example.com" },
    "data": {
        "kind": "content_entry",
        "id": "5ac9e8f2-1d4b-4c7e-9a36-2f8b0d1e7c54",
        "contentType": "article",
        "title": "Autumn catalogue"
    }
}

Verifying a delivery

The signature is HMAC-SHA256 over "{t}.{raw body}", hex, keyed by the endpoint’s secret. Verify the raw bytes, reject timestamps older than five minutes, compare in constant time.

import express from 'express';
import { verifySignature } from '@orthacms/webhooks-domain';

const app = express();
const seen = new Set(); // use Redis or your database in production

// express.raw: the signature covers the exact bytes, not a re-serialised object
app.post('/orthacms', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  const header = req.get('X-Orthacms-Signature') ?? '';
  if (!verifySignature(process.env.ORTHACMS_WEBHOOK_SECRET, header, raw)) {
      return res.sendStatus(401); // 4xx = dead, no retry
  }

  const eventId = req.get('X-Orthacms-Event-Id');
  if (seen.has(eventId)) return res.sendStatus(200); // already handled
  seen.add(eventId);

  const payload = JSON.parse(raw);
  res.sendStatus(204); // answer fast; work after
  queueRebuild(payload.data.contentType, payload.data.id);
});

import { createHmac, timingSafeEqual } from 'node:crypto';

/**
* @param {string} secret   the endpoint's secret, whsec_…
* @param {string} header   the X-Orthacms-Signature header, t=…,v1=…
* @param {string} rawBody  the request body exactly as received
*/
export function verifyOrthaSignature(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(
      header.split(',').map((part) => part.trim().split('='))
  );
  const timestamp = Number(parts.t);
  const received = (parts.v1 ?? '').toLowerCase();
  if (!Number.isInteger(timestamp) || !/^[0-9a-f]+$/.test(received)) {
      return false;
  }

  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > tolerance) return false;

  const expected = createHmac('sha256', secret)
      .update(timestamp + '.' + rawBody)
      .digest('hex');
  if (expected.length !== received.length) return false;

  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

verifySignature(secret, header, rawBody, now?, toleranceSeconds = 300) from @orthacms/webhooks-domain is the same code the CMS signs with.

Retries

• 20 consecutive dead deliveries disable the endpoint; the reason shows in the admin. Re-enabling resets the counter. The list tells the two apart: an endpoint someone paused reads Paused, one the worker switched off Stopped — and while any is stopped, Home’s Needs your attention shows a card for it to anyone holding webhooks:read.
• States: pending → delivering → succeeded | failed (retry scheduled, see nextAttemptAt) | dead.
• Finished deliveries are pruned after retentionDays, at most hourly.

URL policy

Checked on save (422 on refusal) and on every send, after DNS resolution:

• https:// only, unless allowInsecureUrls.
• No username or password in the URL.
• Public addresses only, unless allowPrivateNetworks: loopback, link-local (incl. 169.254.169.254), RFC 1918, CGNAT, test, multicast and reserved ranges are refused, IPv4-mapped IPv6 included.

Admin API

All under /api, global (no X-Workspace-Id), session-authenticated.

Both keys are admin-only — an endpoint reaches across workspaces and its log records where the installation talks to. A delivery id from another endpoint is a 404. Full table: endpoint reference.

Limits

See reacting to changes for cache invalidation and rebuild patterns.