Postream

Carregando o índice…

Documentação: Webhooks

Webhooks

Avisos assinados para o blog quando um post é publicado, atualizado ou sai do ar, e para acompanhar a geração.

Com revalidate: 300, uma publicação leva até 5 minutos para aparecer no blog. Com um webhook, o Postream faz um POST assinado para um endereço do blog sempre que um post muda no ar, e o blog revalida só as páginas afetadas, na hora. A borda do Cloudflare já foi purgada pelo próprio Postream, então a busca seguinte traz o post novo.

Cadastrar

No painel, em Webhooks (até 5 por site): informe o endereço e os eventos. O segredo (whsec_...) aparece uma única vez, na criação; o Postream o guarda cifrado. O painel mostra as últimas 50 entregas de cada webhook, com o status e o botão Reenviar.

O endereço precisa ser público: http ou https nas portas padrão. Endereços privados (localhost, rede interna) são recusados a cada tentativa, inclusive se o DNS mudar.

Eventos de post

EventoQuando
post.publishedUma versão foi publicada (na hora ou pelo agendamento).
post.unpublishedUma versão publicada saiu do ar (despublicada, post ou site excluído).
post.updatedUma versão publicada mudou: título, corpo ou slug editado no painel, ou uma nova execução a devolveu para revisão (ela sai do ar).

Cancelar um agendamento não gera evento: a versão nunca esteve no ar.

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.exemplo.com" },
  "post": { "id": "7c0e…", "slug": "como-gerir-varios-blogs", "locale": "pt-BR", "publishedAt": "2026-10-28T12:00:00.000Z" },
  "paths": ["/blog/como-gerir-varios-blogs"]
}

paths lista as páginas a revalidar. Num post.updated que trocou o slug, vêm o novo e o antigo.

Eventos de geração

Para o sistema do cliente acompanhar o pipeline. O formulário do painel deixa só os de post marcados por padrão; eles não têm paths, então assine-os num endereço que os trate.

EventoQuando
run.awaiting_approvalA geração parou na aprovação do texto de origem.
run.completedTodas as etapas e idiomas passaram (versões em revisão).
run.failedUma etapa falhou de vez; errorCode traz o código estável (VALIDATION_FAILED, MODEL_REFUSAL…).
run.pausedNenhuma chave de IA do workspace está utilizável (CREDENTIAL_INVALID, CREDENTIAL_MISSING…); retoma sozinha quando uma chave volta.
{
  "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"
}

Só ids, status, idiomas e o código de erro: nunca o texto do post nem chave. post é null na geração de pautas (kind: "topics").

Assinatura e novas tentativas

  • X-Postream-Signature é "sha256=" + hex(HMAC-SHA256(segredo, "<X-Postream-Timestamp>.<corpo cru>")). Calcule sobre o corpo exatamente como chegou, antes de qualquer JSON.parse.
  • Responda 2xx em até 10 s. 5xx, 408, 429, timeout ou erro de rede: nova tentativa depois de 30 s, 2 min, 10 min, 1 h e 6 h (6 tentativas no total). Qualquer outra resposta (4xx, redirecionamento) encerra a entrega. Redirecionamentos não são seguidos.
  • A mesma entrega pode chegar mais de uma vez: X-Postream-Delivery é igual em todas as tentativas, então use-o para ignorar repetidas, ou só revalide, que é idempotente.

Exemplo: route handler do Next.js

.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(); // corpo cru: a assinatura é sobre ele
  const timestamp = req.headers.get("x-postream-timestamp") ?? "";
  const signature = req.headers.get("x-postream-signature") ?? "";
 
  // Recusa entregas velhas (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"); // a listagem
  // Se o fetch da API usa `next: { tags: ["postream"] }`, isto basta:
  revalidateTag("postream");
 
  return Response.json({ ok: true });
}

O 400 e o 401 encerram a entrega (não há nova tentativa), o que é o certo para assinatura inválida. Um erro inesperado no handler vira 500 e o Postream tenta de novo.