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
| Evento | Cuándo |
|---|---|
post.published | Se publicó una versión (al instante o por la programación). |
post.unpublished | Una versión publicada salió del aire (despublicada, post o sitio eliminado). |
post.updated | Una 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.
| Evento | Cuándo |
|---|---|
run.awaiting_approval | La generación se detuvo en la aprobación del texto de origen. |
run.completed | Todas las etapas e idiomas pasaron (versiones en revisión). |
run.failed | Una etapa falló de forma definitiva; errorCode trae el código estable (VALIDATION_FAILED, MODEL_REFUSAL…). |
run.paused | Ninguna 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-Signaturees"sha256=" + hex(HMAC-SHA256(secreto, "<X-Postream-Timestamp>.<cuerpo crudo>")). Calcúlala sobre el cuerpo exactamente como llegó, antes de cualquierJSON.parse.- Responde
2xxen 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-Deliveryes igual en todos los intentos, así que úsalo para ignorar las repetidas, o solo revalida, que es idempotente.
Ejemplo: route handler de 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(); // 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.