Webhooks

Cree los webhooks en Studio, en Integrations → Webhooks. Cada uno tiene una URL HTTPS, los eventos que recibe y un secreto de firma que empieza por whsec_, que se muestra una sola vez.

Atlas solo entrega a direcciones HTTPS públicas. Las direcciones de redes privadas se rechazan; el HTTP simple solo se permite hacia localhost mientras desarrolla.

Solicitud

POST https://your-site.example/api/atlas/webhook
Content-Type: application/json
X-Atlas-Event: content.page.published
X-Atlas-Delivery: <unique delivery id>
X-Atlas-Signature: t=1761210000,v1=5f2b…

Verifique cada solicitud

app/api/atlas/webhook/route.ts

import { createHmac, timingSafeEqual } from 'node:crypto';
import { revalidatePath, revalidateTag } from 'next/cache';

const seen = new Set<string>(); // use a shared store (Redis, KV) when you run several instances

export async function POST(request: Request) {
  const body = await request.text(); // the raw body, before any JSON parsing
  const header = request.headers.get('x-atlas-signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)));
  const timestamp = Number(parts.t);

  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300)
    return new Response(null, { status: 400 });

  const expected = createHmac('sha256', process.env.ATLAS_WEBHOOK_SECRET!)
    .update(`${timestamp}.${body}`)
    .digest();
  const given = Buffer.from(String(parts.v1 ?? ''), 'hex');
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
    return new Response(null, { status: 401 });
  }

  const delivery = request.headers.get('x-atlas-delivery') ?? '';
  if (seen.has(delivery)) return new Response(null, { status: 200 }); // already handled
  seen.add(delivery);

  const payload = JSON.parse(body); // e.g. { pageId, route, revision } for content.page.published
  if (typeof payload.route === 'string') revalidatePath(payload.route);
  else revalidateTag('atlas'); // entries, globals, translations: refresh everything tagged 'atlas'
  return new Response(null, { status: 200 });
}

Las comprobaciones, en orden:

1. Use el cuerpo sin procesar de la solicitud.
2. Rechace las marcas de tiempo con más de 5 minutos de antigüedad.
3. Calcule HMAC-SHA256("<t>.<raw body>") con su secreto de firma y compare en tiempo constante.
4. Ignore los ids X-Atlas-Delivery repetidos.

Registre el tipo de evento y el id de entrega, nunca el cuerpo ni el secreto.

Eventos

El cuerpo de la solicitud es la carga útil del evento. Para content.page.published es { "pageId", "route", "revision" }. El tipo de evento está en el encabezado X-Atlas-Event.

Los webhooks se configuran una sola vez, en Desarrollo, y también reciben eventos del sitio web en vivo. Cada carga útil incluye environment: "development" o "production", para que pueda distinguirlos.

Evento	Cuándo
content.page.published	Se publica una página o se revierte
content.page.unpublished	Se retira una página del sitio web
content.page.route.changed	Una página pasa a una nueva dirección (se añade una redirección)
content.entry.published	Se publica una entrada de colección
content.entry.unpublished	Se retira una entrada de colección del sitio web
content.global.published	Se publica el encabezado, el pie de página u otro global
content.translation.published	Se publica una traducción
contract.activated	Se activa un nuevo contrato del sitio
seo.redirects.changed	Cambian las redirecciones
media.asset.uploaded	Se sube un archivo multimedia
form.published	Se publica un formulario
form.submission.accepted	Se acepta el envío de un formulario
lead.created	Llega un nuevo cliente potencial (solo ids, sin datos personales)
lead.merged	Un cliente potencial se fusiona con otro (solo ids)
bot.published	Se publica un chatbot

Atlas espera hasta 10 segundos su respuesta y no sigue redirecciones. Use el historial de entregas de Studio para inspeccionar las cargas útiles y los fallos.