Postream

Cargando el índice…

Documentación: Webhooks

Webhooks

Avisos firmados para el blog cuando un post se publica, se actualiza o sale del aire, y para seguir la generación.

Con revalidate: 300, una publicación tarda hasta 5 minutos en aparecer en el blog. Con un webhook, Postream hace un POST firmado a una dirección del blog cada vez que un post cambia en el aire, y el blog revalida solo las páginas afectadas, al instante. El borde de Cloudflare ya lo purgó el propio Postream, así que la búsqueda siguiente trae el post nuevo.

Registrar

En el panel, en Webhooks (hasta 5 por sitio): indica la dirección y los eventos. El secreto (whsec_...) aparece una sola vez, al crearlo; Postream lo guarda cifrado. El panel muestra las últimas 50 entregas de cada webhook, con el estado y el botón Reenviar.

La dirección tiene que ser pública: http o https en los puertos estándar. Las direcciones privadas (localhost, red interna) se rechazan en cada intento, incluso si el DNS cambia.

Eventos de post

EventoCuándo
post.publishedSe publicó una versión (al instante o por la programación).
post.unpublishedUna versión publicada salió del aire (despublicada, post o sitio eliminado).
post.updatedUna versión publicada cambió: título, cuerpo o slug editado en el panel, o una nueva ejecución la devolvió a revisión (sale del aire).

Cancelar una programación no genera evento: la versión nunca estuvo en el aire.

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

paths lista las páginas a revalidar. En un post.updated que cambió el slug, vienen el nuevo y el antiguo.

Eventos de generación

Para que el sistema del cliente siga el pipeline. El formulario del panel deja marcados por defecto solo los de post; estos no tienen paths, así que suscríbelos en una dirección que los trate.

EventoCuándo
run.awaiting_approvalLa generación se detuvo en la aprobación del texto de origen.
run.completedTodas las etapas e idiomas pasaron (versiones en revisión).
run.failedUna etapa falló de forma definitiva; errorCode trae el código estable (VALIDATION_FAILED, MODEL_REFUSAL…).
run.pausedNinguna clave de IA del workspace se puede usar (CREDENTIAL_INVALID, CREDENTIAL_MISSING…); se reanuda sola cuando vuelve una clave.
{
  "event": "run.failed",
  "workspace": { "id": "…" },
  "site": { "id": "…" },
  "post": { "id": "7c0e…" },
  "run": { "id": "…", "kind": "post_full", "status": "failed" },
  "locales": ["es", "en-US"],
  "errorCode": "MODEL_REFUSAL"
}

Solo ids, estado, idiomas y el código de error: nunca el texto del post ni claves. post es null en la generación de temas (kind: "topics").

Firma y reintentos

  • X-Postream-Signature es "sha256=" + hex(HMAC-SHA256(secreto, "<X-Postream-Timestamp>.<cuerpo crudo>")). Calcúlala sobre el cuerpo exactamente como llegó, antes de cualquier JSON.parse.
  • Responde 2xx en hasta 10 s. 5xx, 408, 429, timeout o error de red: nuevo intento después de 30 s, 2 min, 10 min, 1 h y 6 h (6 intentos en total). Cualquier otra respuesta (4xx, redirección) termina la entrega. Las redirecciones no se siguen.
  • La misma entrega puede llegar más de una vez: X-Postream-Delivery es igual en todos los intentos, así que úsalo para ignorar las repetidas, o solo revalida, que es idempotente.

Ejemplo: route handler de 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(); // cuerpo crudo: la firma es sobre él
  const timestamp = req.headers.get("x-postream-timestamp") ?? "";
  const signature = req.headers.get("x-postream-signature") ?? "";
 
  // Rechaza entregas viejas (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"); // el listado
  // Si el fetch de la API usa `next: { tags: ["postream"] }`, con esto basta:
  revalidateTag("postream");
 
  return Response.json({ ok: true });
}

El 400 y el 401 terminan la entrega (no hay nuevo intento), que es lo correcto para una firma inválida. Un error inesperado en el handler se convierte en 500 y Postream lo intenta de nuevo.