Integração Next.js

Com a integração, cada artigo aprovado e agendado no Postline vai ao ar no seu site Next.js. O site lê os artigos publicados pela API de leitura, guarda em cache, e o Postline avisa por webhook quando algo muda. Depois do primeiro deploy, publicar não pede mudança de código.

RequisitosCopiar link

• Next.js 13.4 ou mais novo, com o App Router. O Pages Router não é suportado.
• Um site que roda em Node.js: Vercel, Netlify ou o seu servidor. Cloudflare via OpenNext ainda não é suportado.
• Um projeto no Postline.

InstalarCopiar link

npx @postline/cli init

npm install @postline/next @postline/sdk server-only

Variáveis de ambienteCopiar link

Na VercelCopiar link

Em Settings › Environment Variables, adicione cada variável para Production (e Preview, se quiser o blog nas prévias), ou pela linha de comando:

vercel env add POSTLINE_PROJECT_ID production
vercel env add POSTLINE_READ_TOKEN production
vercel env add POSTLINE_WEBHOOK_SECRET production

Depois, publique de novo (vercel --prod ou um push) para o deploy ler as variáveis.

Como o cache funcionaCopiar link

O site lê os artigos com tags de cache e o webhook expira essas tags quando algo muda. Um artigo publicado depois do build aparece na primeira visita, sem novo deploy.

• Cache Components (Next.js 16 com cacheComponents: true): lib/postline.ts usa "use cache", cacheTag(...) e cacheLife({ revalidate: 300 }).
• Cache do fetch (os outros casos): cada leitura leva next: { tags, revalidate: 300 }.

Os 300 segundos são uma rede de segurança para um webhook que não chegue. As tags:

A cada evento, o webhook expira as tags do artigo e os caminhos do blog: a lista, o artigo (e o slug anterior, quando mudou), rss.xml e sitemap.xml. Ele nunca aplica o conteúdo do evento: a próxima visita lê a origem, então um evento atrasado não traz de volta uma revisão antiga.

Eventos do siteCopiar link

O Postline manda ao /api/postline/webhook do site:

Cada evento vem no envelope de todos os eventos, com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature do Standard Webhooks. O data traz o artigo:

{
  "id": "evt_9a7c…",
  "type": "article.published",
  "version": 1,
  "timestamp": "2026-10-17T12:00:00.000Z",
  "organizationId": "Zx9…",
  "projectId": "c3a8f2d0-…",
  "data": {
    "articleId": "0b9c4e7a-…",
    "revision": 3,
    "locale": "pt-BR",
    "slug": "onboarding-que-segura-clientes",
    "previousSlug": null,
    "sequence": 42
  }
}

createWebhookHandler confere a assinatura sozinho. Uma resposta que não seja 2xx é repetida, com o mesmo webhook-id.

Rotacionar as chavesCopiar link

A chave do webhook pode ser trocada sem perder entregas: depois de uma rotação, a chave anterior continua assinando por 24 horas.

• No Postline: na conexão do site, Rotacionar segredo mostra a chave nova uma vez.
• Pelo CLI: rodar npx @postline/cli init de novo emite um token de leitura e uma chave de webhook novos. O CLI move a chave atual para POSTLINE_PREVIOUS_WEBHOOK_SECRET no .env.local.

Depois, na hospedagem:

1. POSTLINE_WEBHOOK_SECRET recebe a chave nova; POSTLINE_PREVIOUS_WEBHOOK_SECRET, a anterior (e POSTLINE_READ_TOKEN o token novo, se rodou o init).
2. Publique.
3. Depois de 24 horas, apague POSTLINE_PREVIOUS_WEBHOOK_SECRET e publique de novo.

Referência do @postline/nextCopiar link

Para servidor (importa server-only). Os arquivos que o init escreve já usam tudo isto.

createPostline(config)Copiar link

As leituras do site, com as tags que o webhook expira.

import { createPostline } from "@postline/next"

const site = createPostline({
  projectId: process.env.POSTLINE_PROJECT_ID!,
  token: process.env.POSTLINE_READ_TOKEN!,
  apiUrl: "https://app.postline.com.br",
  locale: "pt-BR",
  basePath: "/blog",
  cacheMode: "fetch-cache", // ou "cache-components"
})

const { data, nextCursor } = await site.articles() // uma página da lista
const article = await site.article("onboarding-que-segura-clientes") // ou null
site.tags // ["postline:<projectId>", "postline:<projectId>:pt-BR"]

createWebhookHandler(config)Copiar link

O Route Handler de /api/postline/webhook. Confere a assinatura do Standard Webhooks (até 5 minutos de diferença, corpo até 64 KB), valida o evento e expira tags e caminhos.

import { createWebhookHandler } from "@postline/next"
import { revalidatePath, revalidateTag } from "next/cache"

export async function POST(request: Request) {
  return createWebhookHandler({
    projectId: process.env.POSTLINE_PROJECT_ID!,
    secret: process.env.POSTLINE_WEBHOOK_SECRET!,
    previousSecret: process.env.POSTLINE_PREVIOUS_WEBHOOK_SECRET,
    basePath: "/blog",
    revalidateTag,
    revalidatePath,
    // Opcional: o seu tratamento, depois de expirar o cache.
    onEvent: async (event) => {
      // event é o envelope; um erro aqui faz o Postline tentar de novo
    },
  })(request)
}

onEvent recebe o envelope (WebhookEvent).

createHealthHandler(config)Copiar link

O Route Handler de /api/postline/health, lido pela verificação da conexão. Responde { ok, projectId, nextVersion, cacheMode } e, com ?challenge=…, também proof: o HMAC-SHA256 de health:<challenge> com a chave do webhook.

import { createHealthHandler } from "@postline/next"

export async function GET(request: Request) {
  return createHealthHandler({
    projectId: process.env.POSTLINE_PROJECT_ID!,
    secret: process.env.POSTLINE_WEBHOOK_SECRET!,
    nextVersion: "16.0.0",
    cacheMode: "fetch-cache",
  })(request)
}

tagsFor(projectId, event) e WebhookEventCopiar link

tagsFor devolve as três tags de um artigo ({ articleId, locale }, como em event.data), para expirar à mão. WebhookEvent é o tipo do envelope de um evento do site.