Webhook Reference

This is the end-to-end reference for theStacc's Custom Webhook integration. It covers everything a developer needs to ship a production receiver: how authentication works, every event we send, every field we put in the payload, what to return, how retries and idempotency behave, and ready-to-paste receiver and database-schema examples.

Quick orientation: if you're configuring this from theStacc's dashboard, start at Connect Platforms and choose Custom Webhook. This page is for the developer who needs to build (or audit) the receiving endpoint. For what happens when a publish fails and how to recover, see Publishing Errors & Retries.

When to use a webhook#

Choose the Custom Webhook integration when:

• Your site is built on a custom stack — Next.js, Astro, Remix, SvelteKit, Rails, Django, Laravel, etc. (anything that isn't one of our direct integrations).
• You want full control over what happens when a blog publishes — write to your own database, trigger a rebuild, push to a CDN, fan out to other systems.
• You already have a CMS but want theStacc to write into it via your own API, not theStacc's direct integrations.

If you use WordPress, Webflow, Ghost, Shopify, or Zepio, use those integrations instead — they handle authentication, image uploads, and field mapping for you. See Connect Platforms for the full list.

How the handshake works#

theStacc uses stateless per-request authentication via a shared secret — the same model as Stripe, GitHub, and Slack webhooks. There is no OAuth dance, no token exchange, no TLS-mutual-auth. The "handshake" happens once during setup: both sides record the same secret, then every subsequent request is independently signed and verified.

Step 1 — One-time setup#

The developer pastes a Webhook URL and Secret Key into the Content SEO > Settings > Publishing dialog when adding a Custom Webhook. theStacc stores the secret; the developer keeps a copy in an env var on their server. After this, both sides hold the same secret.

Step 2 — Per request (every blog publish, sync, unpublish, delete)#

theStacc serializes the payload to JSON, computes sig = HMAC-SHA256(secret, body), and POSTs the body to your webhook URL with the signature in the X-Webhook-Signature header. Your receiver reads the raw body bytes (not the parsed JSON), recomputes the same HMAC with its own copy of the secret, and compares. If the two signatures match, the request is authentic — process it and respond 200 with the live URL and your CMS id. If they don't, return 401.

Both sides compute the same signature independently. If they match, the receiver knows the request really came from theStacc and wasn't modified in transit. That's the entire authentication mechanism.

The shared secret is the entire defense. Anyone who guesses your webhook URL but doesn't know the secret cannot forge a request. Treat it like a database password — store it in env vars, rotate it if leaked, and never commit it to git.

30-minute production setup#

A field-tested path from "we picked Webhook" to "first blog publishes live":

1. Generate a secret — openssl rand -hex 32 (the secret must be 16+ characters, which theStacc enforces at save time).
2. Add an env var to your hosting platform: STACC_WEBHOOK_SECRET=<the secret>.
3. Add a database table for incoming blogs (schema templates below).
4. Add a receiver route at, for example, POST /api/stacc-webhook (examples in six languages below).
5. Deploy. Note the public HTTPS URL.
6. In theStacc: go to Content SEO > Settings > Publishing, add a Custom Webhook, enter the URL and secret, then click Test Connection. A green check means it's working.
7. Click Sample Payload to validate your full publish handler with a fake blog (blog_id will start with preview-).
8. Approve a blog and publish. The first real blog should land in your database within a few seconds.

If anything fails, the Troubleshooting section below covers every error we've seen, and Publishing Errors & Retries explains how theStacc surfaces and recovers from a failed publish.

Authentication: HMAC-SHA256 signing#

When you configure a webhook secret, every request includes a signature in the X-Webhook-Signature header.

How theStacc generates the signature#

# What runs in production
import hmac, hashlib

signature = hmac.new(
    secret.encode(),
    payload_bytes,   # the EXACT bytes POSTed in the body
    hashlib.sha256,
).hexdigest()

headers = {
    "Content-Type": "application/json",
    "X-Webhook-Signature": signature,  # 64-char lowercase hex string
}

Critical detail: the signature is always computed over the exact bytes theStacc puts on the wire, and theStacc POSTs those same bytes as the body. Your receiver MUST hash the raw body bytes it received, not parse-and-re-serialize the JSON. If you re-serialize, whitespace and key order can shift and the signature won't match. This is the single most common integration mistake.

Why "hash the raw bytes" matters even more than it looks. theStacc has two internal publish paths — a manual path (you click Publish) and an autopilot path (theStacc publishes on a schedule). The two paths serialize the JSON slightly differently internally (one compact, one with spacing), but each path always signs the exact bytes it sends. A receiver that hashes the raw body works identically on both paths. A receiver that re-serializes the parsed JSON can pass on one path and fail on the other. Hash the raw bytes and you never have to think about this.

Properties of the signature#

Legacy X-Fairview-Signature compatibility header#

On autopilot (scheduled) publishes, theStacc sends a second signature header alongside X-Webhook-Signature:

X-Webhook-Signature: 9f86d08...            (64-char hex, no prefix)
X-Fairview-Signature: sha256=9f86d08...    (same hex, with a sha256= prefix)

X-Fairview-Signature is a legacy compatibility header retained for receivers built before the standard X-Webhook-Signature header existed. Both headers carry the same HMAC-SHA256 of the same body bytes, so you can verify against either one. New receivers should read X-Webhook-Signature and ignore X-Fairview-Signature. Note that X-Fairview-Signature is sha256=-prefixed, so strip the sha256= prefix before comparing if you choose to use it.

Replay-attack note#

HMAC alone doesn't prevent replay — if an attacker captures a signed request, the signature still validates if they replay the exact same bytes. theStacc embeds a fresh published_at UTC timestamp in every blog event, so receivers can defend by rejecting requests older than a few minutes:

const sentAt = new Date(body.published_at);
const ageSec = (Date.now() - sentAt.getTime()) / 1000;
if (ageSec > 300) return new Response('Too old, possible replay', { status: 401 });

For most receivers this isn't necessary — the dominant threat is "someone guessed our webhook URL" and HMAC fully defends against that.

All events theStacc emits#

Five event types. Branch on the event field at the top of your handler.

Whether theStacc sends blog.published or blog.updated is decided by whether your receiver has published this blog before: the first successful publish fires blog.published; any subsequent re-publish or content sync of the same blog fires blog.updated. Treat both the same way — upsert on blog_id.

A note on preview- prefixed blog_ids: when the user clicks Sample Payload in the dashboard, theStacc fires a real-shaped blog.published event but with blog_id: "preview-00000000-0000-0000-0000-000000000000". Your handler should detect the prefix and skip the actual database write so test runs don't pollute production data.

test.ping payload#

{
  "event": "test.ping",
  "message": "This is a test from theStacc",
  "timestamp": "2026-04-30T12:00:00Z"
}

Respond 200 {"ok": true}. Do not require title, slug, or content for this event — there are none.

blog.published / blog.updated payload#

{
  "event": "blog.published",
  "blog_id": "8f3e1d2c-49ab-4d10-9e7f-7c0bf298faa4",
  "title": "10 SEO mistakes to avoid in 2026",
  "slug": "10-seo-mistakes-to-avoid-in-2026",
  "content": "<h2>Introduction</h2><p>If you've been running SEO...</p>",
  "excerpt": "A short summary of the blog post.",
  "excerpt_short": "A short summary of the blog post.",
  "meta_title": "10 SEO mistakes to avoid in 2026",
  "meta_description": "Avoid these 10 common SEO pitfalls...",
  "featured_image_url": "https://cdn.thestacc.com/blogs/abc123.jpg",
  "categories": ["SEO"],
  "tags": ["seo", "2026", "marketing"],
  "keyword": "seo mistakes 2026",
  "published_at": "2026-04-30T12:00:00Z",
  "images": [
    { "url": "https://cdn.thestacc.com/blog_images/proj-x/blog-y/illustration-1.png", "alt": "How keyword cannibalization happens" },
    { "url": "https://cdn.thestacc.com/blog_images/proj-x/blog-y/illustration-2.png", "alt": "Site audit checklist diagram" }
  ]
}

On autopilot (scheduled) publishes, the same payload additionally carries two retry-related fields — idempotency_key and publish_attempt. See Idempotency & retries below for exactly when they appear and how to use them.

blog.unpublished / blog.deleted payload#

{
  "event": "blog.unpublished",
  "blog_id": "8f3e1d2c-49ab-4d10-9e7f-7c0bf298faa4",
  "title": "10 SEO mistakes to avoid in 2026"
}

For these events, look up the post in your CMS using the blog_id (which you should have stored when handling the original blog.published) and delete or hide it.

Field reference#

Every field theStacc sends in a blog.published / blog.updated event:

The hero image is stripped from content. Every generated blog carries its hero image both as featured_image_url and (originally) inlined as the first <img> in the body. theStacc removes that inline duplicate before sending, so content won't render the hero twice and images[] won't list the hero URL. Render the hero from featured_image_url and the body images from inside content (or mirror them via images[]).

Field length is not enforced at the API level. Postgres TEXT columns are unbounded, and theStacc-generated content stays well within the practical limits above. If you want hard caps in your database schema, the limits in the table are safe defaults.

Response contract#

Your receiver should return a JSON body. theStacc reads two fields from it:

{
  "ok": true,
  "url": "https://your-cms.com/blog/10-seo-mistakes-to-avoid-in-2026",
  "id": "your-internal-cms-post-id"
}

A non-JSON 2xx response still counts as a successful publish — theStacc just won't have a URL or external id to store. For preview / test calls (test.ping, or blog_id starts with preview-), it's fine to skip both fields and return {"ok": true, "skipped": true}.

Idempotency and retries#

How retries behave depends on which path published the blog. Both paths fire the same events at the same URL — the difference is whether theStacc retries automatically.

Manual publish (you click Publish)#

A manual publish is single-shot. If your endpoint times out (the request budget is ~30 seconds) or returns a non-2xx status, the publish fails immediately and the user sees a "Failed to publish" notice. The user clicks Republish to try again. theStacc does not auto-retry a manual publish.

Autopilot publish (theStacc publishes on a schedule)#

Autopilot publishes retry automatically on transient failures (a timeout, a network error, or a 5xx from your receiver). theStacc makes up to 5 attempts with exponential backoff — roughly 60s, then 120s, 240s, 480s, and 960s, a full retry window of about 30 minutes. After 5 failed attempts the publish is marked failed. A 4xx from your receiver is treated as permanent and is not retried (fix your receiver and re-publish). For the full failure-and-recovery story, see Publishing Errors & Retries.

Why your receiver must be idempotent#

Because autopilot retries, the same blog can arrive at your endpoint more than once. The classic case: theStacc POSTs, your CMS creates the post, but the response packet is lost in transit (a network blip), so theStacc sees a timeout and retries — and a naive receiver creates a duplicate post.

Two fields on autopilot payloads exist specifically to defend against this:

• idempotency_key — a string of the form "{blog_id}:{lifecycle}" that is stable across every retry of a single publish but different across separate publish intents (a fresh publish months later gets a different key). Persist the keys you've already processed and short-circuit on a repeat — that makes your receiver safe even if the same publish is delivered twice.
• publish_attempt — an integer that is 1 on the first attempt and increments (2, 3, ...) on each retry. It's primarily for your logs and observability: publish_attempt > 1 tells you theStacc is retrying after a transient hiccup.

Even without those fields, the simplest and most robust defense is to UPSERT on blog_id so duplicate deliveries (or a user clicking Republish twice) converge on the same row instead of creating two posts.

How theStacc itself avoids duplicates (direct CMS integrations)#

For theStacc's own direct integrations (WordPress, Webflow, Ghost, Shopify), before re-POSTing on a retry theStacc looks up the target CMS by slug and treats an existing post as "already published by us" only if it matches a fingerprint: the same title and a creation timestamp within a ~35-minute window (which comfortably covers the ~30-minute retry sequence plus headroom). If that fingerprint matches, theStacc reuses the existing post instead of creating a duplicate. You don't need to implement this for a webhook receiver — idempotency_key plus an UPSERT on blog_id is simpler and just as safe — but the slug field plus the ~35-minute window is the same idea you can mirror if your CMS lacks a stable id.

Respond fast, do heavy work async#

If your CMS write involves image processing, search re-indexing, or CDN purging, run those in a background job after responding 2xx. A slow synchronous write risks timing out theStacc's request.

export async function POST(request: Request) {
  // ... verify signature, parse body ...
  await db.thestaccBlog.upsert({ /* ... */ }); // fast — just writes the row
  enqueueBackgroundJob('process-blog', body.blog_id); // image upload, ISR revalidate, search index
  return Response.json({ ok: true, url, id });
}

Custom headers#

Each Custom Webhook integration can carry custom request headers — key/value pairs sent with every request. Use them for a bearer token, a static API key, or a routing header your gateway expects:

Authorization: Bearer your-token
X-Tenant: acme-prod

Practical guidance:

• Keep the set small — roughly up to 20 pairs is plenty for any real use (auth + a couple of routing headers). theStacc does not enforce a count, but a sprawling header set usually signals something that belongs in the URL or body instead.
• Content-Type cannot be overridden. theStacc always sends application/json. A custom Content-Type is ignored so your receiver's JSON parser never breaks.
• The signature headers cannot be overridden. Custom headers named X-Webhook-Signature or X-Fairview-Signature are ignored — theStacc always sets the real HMAC. This prevents a misconfigured (or malicious) custom header from spoofing the signature.

Everything else you set is passed through verbatim.

Self-hosting images (optional)#

By default, every <img> inside content and the featured_image_url point at theStacc's CDN (cdn.thestacc.com), served to your visitors directly. That's the simplest setup and works out of the box.

For deeper CMS integration, many sites prefer to host blog images on their own storage alongside the rest of their media library. The images array makes that a one-pass mirror with no HTML parsing required.

How it works#

The images field is a list of {url, alt} objects — one per <img> in the content body, in document order, with duplicates collapsed. Each url is byte-for-byte identical to what's in the corresponding src= attribute inside content, so a plain string find/replace handles the swap reliably.

let content = body.content;

// 1. Mirror every body image.
for (const img of body.images || []) {
  const bytes = await fetch(img.url).then(r => r.arrayBuffer());
  const newUrl = await uploadToMyStorage(bytes, suggestFilename(img.url));
  // The URL string IS the stable identifier — find/replace by full src=.
  content = content.replaceAll(`src="${img.url}"`, `src="${newUrl}"`);
}

// 2. Mirror the featured image separately. It's a top-level field, not
//    in images[] — most CMSes have a dedicated featured-image slot.
let featuredUrl = body.featured_image_url;
if (featuredUrl) {
  const bytes = await fetch(featuredUrl).then(r => r.arrayBuffer());
  featuredUrl = await uploadToMyStorage(bytes, suggestFilename(featuredUrl));
}

// 3. Store `content` (with rewritten src=) and `featuredUrl` in your CMS.

That's the entire pattern. No HTML parser, no DOM library, no positional tracking — the URL is the identifier.

Python receiver#

content = body["content"]

# 1. Mirror body images.
for img in body.get("images", []):
    blob = httpx.get(img["url"]).content
    new_url = upload_to_my_storage(blob, suggest_filename(img["url"]))
    content = content.replace(f'src="{img["url"]}"', f'src="{new_url}"')

# 2. Mirror the featured image separately.
featured_url = body.get("featured_image_url")
if featured_url:
    blob = httpx.get(featured_url).content
    featured_url = upload_to_my_storage(blob, suggest_filename(featured_url))

# 3. Persist content + featured_url to your CMS.

Security: allowlist your fetch host#

Whenever a server-side handler downloads URLs from any external source, allowlist trusted hosts before issuing the request. For theStacc images, the trusted host is cdn.thestacc.com:

const ALLOWED_HOSTS = new Set(['cdn.thestacc.com']);

async function safeFetch(url) {
  const parsed = new URL(url);
  if (parsed.protocol !== 'https:') throw new Error(`Refusing non-HTTPS URL: ${url}`);
  if (!ALLOWED_HOSTS.has(parsed.hostname)) throw new Error(`Untrusted host: ${parsed.hostname}`);
  return fetch(url);
}

for (const img of body.images || []) {
  const bytes = await safeFetch(img.url).then(r => r.arrayBuffer());
  // ...then upload + find/replace as before.
}

Apply the same allowlist to featured_image_url. With it in place, every body and featured image fetches through a single auditable choke point.

Notes#

• Featured image is NOT in images[]. It's a separate top-level field (featured_image_url). theStacc strips the inline hero from content before sending so the page doesn't render the same image twice.
• Duplicate URLs are deduped. If the same body image appears twice, the array lists it once. Your content.replaceAll(...) swaps every occurrence in one pass anyway.
• alt may be empty. Decorative images and images the generator didn't caption ship with alt: "". Pass it through verbatim to preserve accessibility on your re-hosted copy.
• Backward compatible. Receivers that ignore images continue working unchanged — every other field is identical to before this field was added.
• The URL is the stable identifier. theStacc does not inject any per-image marker attribute into the <img> tags. URLs in images[] mirror content verbatim, so a one-to-one find/replace works without any normalization step.

Migrating blogs already published with theStacc's URLs#

If you have blogs already in your CMS with theStacc CDN URLs and you want to switch them to self-hosted images:

1. Open each blog in theStacc and click Publish to re-publish.
2. The webhook fires as blog.updated with the images array.
3. Your receiver runs the mirror loop above and updates the post (same blog_id means the same CMS record).
4. The CMS post now stores your URLs instead of theStacc's.

There's no bulk-republish API — for most accounts this is a one-shot migration of a handful of posts.

Database schema templates#

Pick the database you already use. Each schema below maps directly to the webhook payload — no transformation needed.

Postgres#

CREATE TABLE thestacc_blogs (
    blog_id           UUID PRIMARY KEY,
    title             TEXT NOT NULL,
    slug              TEXT NOT NULL UNIQUE,
    content           TEXT NOT NULL,
    excerpt           TEXT,
    meta_title        TEXT,
    meta_description  TEXT,
    featured_image_url TEXT,
    keyword           TEXT,
    categories        TEXT[] NOT NULL DEFAULT '{}',
    tags              TEXT[] NOT NULL DEFAULT '{}',
    published_at      TIMESTAMPTZ NOT NULL,
    last_event        TEXT NOT NULL,
    received_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    cms_post_id       TEXT,
    is_unpublished    BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE INDEX idx_thestacc_blogs_slug ON thestacc_blogs(slug);
CREATE INDEX idx_thestacc_blogs_published_at ON thestacc_blogs(published_at DESC);
CREATE INDEX idx_thestacc_blogs_active ON thestacc_blogs(published_at DESC) WHERE is_unpublished = FALSE;

MySQL / MariaDB#

CREATE TABLE thestacc_blogs (
    blog_id            CHAR(36) PRIMARY KEY,
    title              VARCHAR(255) NOT NULL,
    slug               VARCHAR(255) NOT NULL UNIQUE,
    content            LONGTEXT NOT NULL,
    excerpt            TEXT,
    meta_title         VARCHAR(255),
    meta_description   VARCHAR(500),
    featured_image_url VARCHAR(2048),
    keyword            VARCHAR(255),
    categories         JSON NOT NULL,
    tags               JSON NOT NULL,
    published_at       DATETIME(3) NOT NULL,
    last_event         VARCHAR(50) NOT NULL,
    received_at        DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    updated_at         DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
    cms_post_id        VARCHAR(255),
    is_unpublished     BOOLEAN NOT NULL DEFAULT FALSE,
    INDEX idx_slug (slug),
    INDEX idx_published_at (published_at DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Prisma (Postgres-flavored)#

model ThestaccBlog {
  blogId            String    @id @map("blog_id") @db.Uuid
  title             String
  slug              String    @unique
  content           String
  excerpt           String?
  metaTitle         String?   @map("meta_title")
  metaDescription   String?   @map("meta_description")
  featuredImageUrl  String?   @map("featured_image_url")
  keyword           String?
  categories        String[]
  tags              String[]
  publishedAt       DateTime  @map("published_at")
  lastEvent         String    @map("last_event")
  receivedAt        DateTime  @default(now()) @map("received_at")
  updatedAt         DateTime  @updatedAt @map("updated_at")
  cmsPostId         String?   @map("cms_post_id")
  isUnpublished     Boolean   @default(false) @map("is_unpublished")

  @@index([slug])
  @@index([publishedAt(sort: Desc)])
  @@map("thestacc_blogs")
}

MongoDB#

db.createCollection("thestaccBlogs", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["blog_id", "title", "slug", "content", "published_at", "last_event"],
      properties: {
        blog_id:            { bsonType: "string" },
        title:              { bsonType: "string" },
        slug:               { bsonType: "string" },
        content:            { bsonType: "string" },
        excerpt:            { bsonType: ["string", "null"] },
        meta_title:         { bsonType: ["string", "null"] },
        meta_description:   { bsonType: ["string", "null"] },
        featured_image_url: { bsonType: ["string", "null"] },
        keyword:            { bsonType: ["string", "null"] },
        categories:         { bsonType: "array", items: { bsonType: "string" } },
        tags:               { bsonType: "array", items: { bsonType: "string" } },
        published_at:       { bsonType: "date" },
        last_event:         { bsonType: "string" },
        cms_post_id:        { bsonType: ["string", "null"] },
        is_unpublished:     { bsonType: "bool" }
      }
    }
  }
});
db.thestaccBlogs.createIndex({ blog_id: 1 }, { unique: true });
db.thestaccBlogs.createIndex({ slug: 1 }, { unique: true });
db.thestaccBlogs.createIndex({ published_at: -1 });

Receiver examples#

Each example is production-ready — it handles every event type, verifies the HMAC signature, dedupes via blog_id, and returns the response shape theStacc expects.

Next.js (App Router)#

// app/api/stacc-webhook/route.ts
import crypto from 'crypto';

const SECRET = process.env.STACC_WEBHOOK_SECRET!;

export async function POST(request: Request) {
  // CRITICAL: read raw bytes BEFORE parsing JSON.
  // request.json() consumes the stream and re-serializing
  // would change byte order/whitespace -> signature mismatch.
  const rawBody = await request.text();

  const sig = request.headers.get('x-webhook-signature') || '';
  const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');

  // Decode both before comparing. Buffer.from with invalid hex returns
  // a shorter buffer (Node stops at the first non-hex char) which would
  // make timingSafeEqual throw RangeError instead of returning false.
  const sigBuf = Buffer.from(sig, 'hex');
  const expBuf = Buffer.from(expected, 'hex');
  const valid =
    sigBuf.length === expBuf.length
    && crypto.timingSafeEqual(sigBuf, expBuf);

  if (!valid) {
    return new Response('Invalid signature', { status: 401 });
  }

  const body = JSON.parse(rawBody);

  if (body.event === 'test.ping') {
    return Response.json({ ok: true });
  }

  if (body.event === 'blog.published' || body.event === 'blog.updated') {
    if (body.blog_id?.startsWith('preview-')) {
      return Response.json({ ok: true, skipped: true });
    }
    const post = await db.thestaccBlog.upsert({
      where: { blogId: body.blog_id },
      create: {
        blogId: body.blog_id,
        title: body.title,
        slug: body.slug,
        content: body.content,
        excerpt: body.excerpt || null,
        metaTitle: body.meta_title || null,
        metaDescription: body.meta_description || null,
        featuredImageUrl: body.featured_image_url || null,
        keyword: body.keyword || null,
        categories: body.categories || [],
        tags: body.tags || [],
        publishedAt: new Date(body.published_at),
        lastEvent: body.event,
      },
      update: {
        title: body.title,
        slug: body.slug,
        content: body.content,
        excerpt: body.excerpt || null,
        metaTitle: body.meta_title || null,
        metaDescription: body.meta_description || null,
        featuredImageUrl: body.featured_image_url || null,
        keyword: body.keyword || null,
        categories: body.categories || [],
        tags: body.tags || [],
        publishedAt: new Date(body.published_at),
        lastEvent: body.event,
        isUnpublished: false,
      },
    });
    return Response.json({
      ok: true,
      url: `https://example.com/blog/${post.slug}`,
      id: post.blogId,
    });
  }

  if (body.event === 'blog.unpublished' || body.event === 'blog.deleted') {
    await db.thestaccBlog.update({
      where: { blogId: body.blog_id },
      data: { isUnpublished: true, lastEvent: body.event },
    });
    return Response.json({ ok: true });
  }

  return Response.json({ error: 'Unknown event' }, { status: 400 });
}

Express#

import express from 'express';
import crypto from 'crypto';

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

// CRITICAL: capture raw body BEFORE express.json() parses it.
app.post('/api/stacc-webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const raw = req.body; // Buffer
    const sig = req.get('x-webhook-signature') || '';
    const expected = crypto.createHmac('sha256', SECRET).update(raw).digest('hex');

    const sigBuf = Buffer.from(sig, 'hex');
    const expBuf = Buffer.from(expected, 'hex');
    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
      return res.status(401).send('Invalid signature');
    }

    const body = JSON.parse(raw.toString('utf8'));
    // ... handle body.event as in the Next.js example
    res.json({ ok: true });
  }
);

Astro (server endpoint)#

// src/pages/api/stacc-webhook.ts
import type { APIRoute } from 'astro';
import crypto from 'crypto';

export const prerender = false; // server-rendered, not static

const SECRET = import.meta.env.STACC_WEBHOOK_SECRET;

export const POST: APIRoute = async ({ request }) => {
  const raw = await request.text();
  const sig = request.headers.get('x-webhook-signature') || '';
  const expected = crypto.createHmac('sha256', SECRET).update(raw).digest('hex');

  const sigBuf = Buffer.from(sig, 'hex');
  const expBuf = Buffer.from(expected, 'hex');
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return new Response('Invalid signature', { status: 401 });
  }

  const body = JSON.parse(raw);
  // ... handle events as in the Next.js example
  return new Response(JSON.stringify({ ok: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

Python / FastAPI#

import hmac, hashlib, os, json
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["STACC_WEBHOOK_SECRET"].encode()

@app.post("/api/stacc-webhook")
async def receive(request: Request):
    raw = await request.body()  # bytes — DON'T re-serialize
    sig = request.headers.get("x-webhook-signature", "")
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, sig):
        raise HTTPException(401, "Invalid signature")

    body = json.loads(raw)

    if body["event"] == "test.ping":
        return {"ok": True}

    if body["event"] in ("blog.published", "blog.updated"):
        if body.get("blog_id", "").startswith("preview-"):
            return {"ok": True, "skipped": True}
        # ... upsert into your DB on blog_id
        return {
            "ok": True,
            "url": f"https://example.com/blog/{body['slug']}",
            "id": body["blog_id"],
        }

    if body["event"] in ("blog.unpublished", "blog.deleted"):
        # ... soft-delete by blog_id
        return {"ok": True}

    raise HTTPException(400, "Unknown event")

Python / Flask#

import hmac, hashlib, os
from flask import Flask, request, abort, jsonify

app = Flask(__name__)
SECRET = os.environ["STACC_WEBHOOK_SECRET"].encode()

@app.post("/api/stacc-webhook")
def receive():
    raw = request.get_data()
    sig = request.headers.get("X-Webhook-Signature", "")
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, sig):
        abort(401)

    body = request.get_json(force=True)
    # ... same event branching as the FastAPI example
    return jsonify({"ok": True})

PHP#

<?php
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('STACC_WEBHOOK_SECRET'));

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Invalid signature');
}

$body = json_decode($raw, true);

switch ($body['event']) {
    case 'test.ping':
        echo json_encode(['ok' => true]);
        break;
    case 'blog.published':
    case 'blog.updated':
        if (str_starts_with($body['blog_id'] ?? '', 'preview-')) {
            echo json_encode(['ok' => true, 'skipped' => true]);
            break;
        }
        // ... upsert into DB on blog_id
        echo json_encode([
            'ok'  => true,
            'url' => "https://example.com/blog/{$body['slug']}",
            'id'  => $body['blog_id'],
        ]);
        break;
    case 'blog.unpublished':
    case 'blog.deleted':
        // ... soft-delete
        echo json_encode(['ok' => true]);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unknown event']);
}

Limits and operational rules#

Troubleshooting#

Concrete error, then cause, then fix. For the user-facing side of these — where the error shows up in theStacc and how to recover — see Publishing Errors & Retries.

Security best practices#

1. Always set a webhook secret. Without one, anyone who guesses your URL can post fake blogs.
2. Use crypto.timingSafeEqual / hmac.compare_digest when comparing signatures — plain === is timing-attack vulnerable.
3. Hash the raw body, not the parsed JSON. Re-serialization changes whitespace and breaks signatures.
4. Store the secret in env vars only. Never commit it to git, never include it in client-side code.
5. Rotate the secret on suspected leak. Generate a new one, update both your env var and theStacc's integration settings, then redeploy. theStacc starts signing with the new secret on the next request.
6. Run your receiver behind HTTPS-only. Add HSTS if you control the domain.
7. Rate-limit the receiver. Even with HMAC, a flood of unauthenticated requests can pressure your endpoint while you reject them. Cloudflare or your hosting platform usually handles this.

FAQ#

How does the handshake work?

There's no traditional handshake — it's stateless per-request authentication. The "handshake" is just storing a shared secret on both sides, once, during setup. Every subsequent request is independently authenticated via HMAC.

What identifies a request as coming from theStacc?

The X-Webhook-Signature header verified against your secret. Nothing else is reliable — anyone can fake the body, the User-Agent, or the source IP.

What's the X-Fairview-Signature header for?

It's a legacy compatibility header sent on autopilot publishes, carrying the same HMAC as X-Webhook-Signature but sha256=-prefixed. New receivers should use X-Webhook-Signature. See Legacy X-Fairview-Signature compatibility header.

Why did the same blog arrive twice?

Autopilot publishes retry automatically on transient failures, so a lost response packet can cause a re-delivery. Dedup on idempotency_key (autopilot payloads include it) or UPSERT on blog_id. See Idempotency & retries.

Can I override the Content-Type or signature headers with a custom header?

No. Content-Type is always application/json, and the signature headers are always set by theStacc. Custom headers with those names are ignored.

What's the maximum title / slug / content length?

theStacc doesn't enforce hard length limits at the API level — generated content stays well within reasonable bounds. If your CMS or DB needs hard caps, the Field reference table lists safe defaults.

What if my receiver is slow or down when a publish happens?

On a manual publish, that publish fails and the user clicks Republish. On an autopilot publish, theStacc retries automatically (up to 5 attempts over ~30 minutes) before marking it failed. See Publishing Errors & Retries.

Can I get historical blogs through the webhook?

No — webhooks are forward-only. For backfills, use the Public Blog API, which lets you fetch all your published blogs.

Do I need to handle test.ping separately?

Yes — it has no blog fields. If your handler tries to read title or content from a test.ping event, it'll error and Test Connection will fail. Branch on event first.

Can theStacc post to multiple webhook URLs?

Yes — set up multiple Custom Webhook integrations on the same project. Each gets its own URL, secret, and headers, and theStacc fires every published blog at every active integration.

Does an agent or the MCP server publishing my blog use a different webhook?

No. Whether a teammate clicks Publish or an automation publishes through the MCP server, the publish flows through the same path and fires the same webhook events at the same URL. See Agent Keys & MCP.

What happens if I delete a blog in theStacc?

We send event: "blog.deleted" with the blog_id and title. Your handler should remove or hide the post. If your receiver fails, the blog stays deleted in theStacc but lingers on your site — periodic reconciliation via the Public Blog API is a defensive option.

Next steps#

• Set up the integration in Connect Platforms
• Understand failure handling in Publishing Errors & Retries
• Automate publishing with Agent Keys & MCP
• Backfill historical content with the Public Blog API