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
| Evento | Quando |
|---|---|
post.published | Uma versão foi publicada (na hora ou pelo agendamento). |
post.unpublished | Uma versão publicada saiu do ar (despublicada, post ou site excluído). |
post.updated | Uma 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.
| Evento | Quando |
|---|---|
run.awaiting_approval | A geração parou na aprovação do texto de origem. |
run.completed | Todas as etapas e idiomas passaram (versões em revisão). |
run.failed | Uma etapa falhou de vez; errorCode traz o código estável (VALIDATION_FAILED, MODEL_REFUSAL…). |
run.paused | Nenhuma 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 qualquerJSON.parse.- Responda
2xxem 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
POSTREAM_WEBHOOK_SECRET=whsec_...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.