Postream

Loading the index…

Docs: Webhooks

Webhooks

Signed notifications to the blog when a post is published, updated or taken offline, and to follow generation.

With revalidate: 300, a publication takes up to 5 minutes to show up on the blog. With a webhook, Postream sends a signed POST to an address on the blog whenever a live post changes, and the blog revalidates only the affected pages, right away. Postream itself has already purged the Cloudflare edge, so the next fetch brings the new post.

Register

In the panel, under Webhooks (up to 5 per site): enter the address and the events. The secret (whsec_...) appears only once, on creation; Postream stores it encrypted. The panel shows the last 50 deliveries of each webhook, with the status and the Resend button.

The address must be public: http or https on the default ports. Private addresses (localhost, internal network) are refused on every attempt, even if the DNS changes.

Post events

EventWhen
post.publishedA version was published (right away or by schedule).
post.unpublishedA published version went offline (unpublished, post or site deleted).
post.updatedA published version changed: title, body or slug edited in the panel, or a new run sent it back to review (it goes offline).

Cancelling a schedule fires no event: the version was never live.

POST /api/postream HTTP/1.1
Content-Type: application/json
User-Agent: PostreamWebhooks/1.0
X-Postream-Event: post.published
X-Postream-Delivery: 3f1c…
X-Postream-Timestamp: 1761652800
X-Postream-Signature: sha256=9b2e…
 
{
  "event": "post.published",
  "site": { "id": "…", "domain": "blog.example.com" },
  "post": { "id": "7c0e…", "slug": "managing-many-blogs", "locale": "en-US", "publishedAt": "2026-10-28T12:00:00.000Z" },
  "paths": ["/blog/managing-many-blogs"]
}

paths lists the pages to revalidate. On a post.updated that changed the slug, both the new and the old one come.

Generation events

For the client's system to follow the pipeline. The panel form only ticks the post events by default; generation events have no paths, so subscribe to them on an address that handles them.

EventWhen
run.awaiting_approvalGeneration stopped at the source text approval.
run.completedAll stages and languages passed (versions in review).
run.failedA stage failed for good; errorCode carries the stable code (VALIDATION_FAILED, MODEL_REFUSAL…).
run.pausedNo AI key in the workspace is usable (CREDENTIAL_INVALID, CREDENTIAL_MISSING…); it resumes on its own when a key comes back.
{
  "event": "run.failed",
  "workspace": { "id": "…" },
  "site": { "id": "…" },
  "post": { "id": "7c0e…" },
  "run": { "id": "…", "kind": "post_full", "status": "failed" },
  "locales": ["pt-BR", "en-US"],
  "errorCode": "MODEL_REFUSAL"
}

Only ids, statuses, languages and the error code: never the post text or a key. post is null for topic generation (kind: "topics").

Signature and retries

  • X-Postream-Signature is "sha256=" + hex(HMAC-SHA256(secret, "<X-Postream-Timestamp>.<raw body>")). Compute it over the body exactly as it arrived, before any JSON.parse.
  • Answer 2xx within 10 s. 5xx, 408, 429, timeout or network error: retry after 30 s, 2 min, 10 min, 1 h and 6 h (6 attempts in total). Any other response (4xx, redirect) ends the delivery. Redirects are not followed.
  • The same delivery may arrive more than once: X-Postream-Delivery is the same on every attempt, so use it to ignore repeats, or just revalidate, which is idempotent.

Example: Next.js route handler

.env
POSTREAM_WEBHOOK_SECRET=whsec_...
app/api/postream/route.ts
import { createHmac, timingSafeEqual } from "crypto";
import { revalidatePath, revalidateTag } from "next/cache";
 
const TOLERANCE_SECONDS = 5 * 60;
 
export async function POST(req: Request) {
  const body = await req.text(); // raw body: the signature is over it
  const timestamp = req.headers.get("x-postream-timestamp") ?? "";
  const signature = req.headers.get("x-postream-signature") ?? "";
 
  // Refuse old deliveries (replay).
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return new Response("stale", { status: 400 });
 
  const expected = Buffer.from(
    `sha256=${createHmac("sha256", process.env.POSTREAM_WEBHOOK_SECRET!).update(`${timestamp}.${body}`).digest("hex")}`,
  );
  const got = Buffer.from(signature);
  if (expected.length !== got.length || !timingSafeEqual(expected, got)) return new Response("bad signature", { status: 401 });
 
  const event = JSON.parse(body) as { event: string; paths: string[] };
  for (const path of event.paths) revalidatePath(path);
  revalidatePath("/blog"); // the list
  // If the API fetch uses `next: { tags: ["postream"] }`, this is enough:
  revalidateTag("postream");
 
  return Response.json({ ok: true });
}

The 400 and the 401 end the delivery (there is no retry), which is right for an invalid signature. An unexpected error in the handler becomes a 500 and Postream tries again.