Connect a custom webhook

• An editor-or-higher SearchChamp role on the site.
• One public https:// endpoint on port 443 that accepts POST requests within 15 seconds.
• A receiver that preserves the raw request bytes, verifies HMAC-SHA256, rejects stale deliveries, and stores idempotency keys.

Every request has:

Compute HMAC-SHA256 over the exact bytes received, using the connection secret. Compare the expected and received digests with a constant-time primitive. Authenticate before parsing, logging, fetching media, or writing data. Reject an invalid timestamp, a delivery outside your replay window, a header/body mismatch, or an already-used key with different bytes.

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

export function verify(rawBody, signatureHeader, secret) {
  const receivedHex = signatureHeader?.match(/^sha256=([0-9a-f]{64})$/)?.[1];
  if (!receivedHex) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(receivedHex, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Do not parse and re-serialize before verification: whitespace and key order change the signed bytes.

All events use envelope version 1 and share these fields:

Receivers must ignore unknown additive fields. Reject an unsupported envelope_version or unknown event; a new field alone does not increment the version.

cw.test_fire also carries a human-readable message and no article payload.

cw.publish carries article_id plus payload, including source article/revision identity, title, fixed slug, status, Markdown/body content, SEO metadata, target keyword, language/direction, tags, image descriptors, and — for enabled workspaces — a resolved payload.author object alongside the schema graph. Treat all author-authored strings and structured data as untrusted input.

When present, payload.author describes the person SearchChamp attributed the article to. Its current wire shape carries these keys; receivers should continue to ignore unknown additive fields:

Three rules matter when you parse it.

1. Optional keys are absent rather than null. This applies to credentials, bio, photo_url, sameas, and profile_url. An omitted bio means there is no bio, not an empty one.
2. The whole object is absent when the workspace is outside the author-metadata rollout, there is no effective author (neither an article assignment nor a site default), or that author has not consented to appear publicly. The article still publishes in all three cases. Apply your own fallback byline rather than blocking the publish.
3. sameas supplies social profiles. The schema graph's Person.url uses profile_url when present; otherwise it uses the first valid sameas URL, then the site's origin. If sameas carries no LinkedIn URL, render no LinkedIn link rather than an empty one.

cw.revert identifies the source article, the receiver's prior cms_post_id, and the revert action. A revert means hide/tombstone reversibly; it does not require destructive deletion.

Image descriptors include a role, source URL, MIME/size metadata where available, and a placeholder token present in the article body. Before making an article visible:

1. Fetch through an SSRF-safe client with DNS/IP checks, no redirects, strict timeouts, image-count and byte limits.
2. Verify the actual bytes and MIME type; do not trust the extension or header alone.
3. Copy the image into storage you own under an immutable revision-specific key.
4. Replace every placeholder with your owned public URL, then sanitize the final HTML.

Never publish a placeholder token, source storage key, credential, private URL, or presigned URL. Define whether a failed hero rejects the publish and whether a failed inline image is removed with a warning; make the policy deterministic and idempotent.

Return 2xx only after the durable publish/update/revert commit completes. A publish acknowledgement should be JSON:

{
  "cms_post_id": "stable-receiver-post-id",
  "published_url": "https://example.com/blog/fixed-slug",
  "receiver_revision_id": "receiver-revision-id",
  "warnings": []
}

cms_post_id must stay stable across republishing. The slug and canonical URL stay fixed; republishing adds revision history. Store workspace, site, source article, source revision token, idempotency key, receiver post/revision IDs, canonical URL, content hash, lifecycle timestamps, verified envelope, and original acknowledgement so the complete identity chain remains joinable.

Store the exact acknowledgement bytes with the idempotency record. An identical retry must return those bytes without duplicating content or media. The same key with different request bytes is a conflict. A revert is idempotent and reversible; later publish may restore visibility as a new revision.

• 2xx: the receiver completed the event durably. Do not acknowledge queueing alone unless your durable queue is the contract boundary and produces the required stable identity.
• 4xx: authentication, stale timestamp, unsupported contract, validation, conflict, or policy rejection. Use a stable safe error code.
• 5xx or timeout: transient receiver failure. Do not claim success.
• 3xx: redirects are blocked.

SearchChamp records a non-2xx or transport failure as a failed delivery. Design your receiver for redelivery even if a particular sender path does not automatically retry: network failures can occur after your commit but before SearchChamp receives the response.

• Verify TLS and raw-body HMAC before parsing or logging.
• Enforce a short issued-at window and durable idempotency uniqueness.
• Validate tenant/source identity, field lengths, slug/path rules, event/version, body size, and media limits.
• Sanitize HTML with an allowlist. Never evaluate incoming MDX, JSX, imports, expressions, scripts, event handlers, or unsafe URLs.
• Keep signing secrets in a secret manager and rotate after suspected exposure.
• Use private encrypted media storage, blocked public access, and least-privilege delivery access.
• Log only redacted event IDs/outcomes; never signatures, secrets, article bodies, presigned URLs, or credentials.
• Test racing duplicates and transaction failures, not only sequential happy paths.

Test valid publish, bad signature, changed raw bytes, stale timestamp, replay/racing duplicate, unknown additive fields, unsupported version/event, invalid slug, large/invalid/partial media, republish, slug refusal, repeated revert, and failure after commit-before-response.

• Test connection says blocked: confirm public HTTPS:443, DNS resolution, certificate validity, and that the endpoint is not private/SearchChamp infrastructure.
• Signature mismatch: capture raw bytes before any JSON middleware; confirm the correct connection secret and sha256= format.
• Stale request: compare UTC clocks and your replay window.
• Duplicate content: enforce a database uniqueness constraint and return the stored acknowledgement.
• Tokens appear in the article: process every image descriptor before final sanitization and scan the rendered output.
• SearchChamp shows failure but the page exists: the response was lost or late; replay the same key and return the original acknowledgement.