Webhooks

Erstellen Sie Webhooks in Studio unter Integrations → Webhooks. Jeder hat eine HTTPS-URL, die Ereignisse, die er erhält, und ein Signaturgeheimnis, das mit whsec_ beginnt und einmalig angezeigt wird.

Atlas liefert nur an öffentliche HTTPS-Adressen aus. Adressen in privaten Netzwerken werden abgelehnt; reines HTTP ist nur an localhost erlaubt, solange Sie entwickeln.

Anfrage

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…

Jede Anfrage verifizieren

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 });
}

Die Prüfungen in der Reihenfolge:

1. Verwenden Sie den rohen Anfragekörper.
2. Lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind.
3. Berechnen Sie HMAC-SHA256("<t>.<raw body>") mit Ihrem Signaturgeheimnis und vergleichen Sie in konstanter Zeit.
4. Ignorieren Sie wiederholte X-Atlas-Delivery-IDs.

Protokollieren Sie Ereignistyp und Delivery-ID, nie den Body oder das Geheimnis.

Ereignisse

Der Anfragekörper ist die Nutzlast des Ereignisses. Für content.page.published ist es { "pageId", "route", "revision" }. Der Ereignistyp steht im Header X-Atlas-Event.

Webhooks werden einmal in Development eingerichtet und erhalten auch Ereignisse von der Live-Website. Jede Nutzlast enthält environment: "development" oder "production", sodass Sie beide unterscheiden können.

Ereignis	Wann
content.page.published	Eine Seite wird veröffentlicht oder zurückgesetzt
content.page.unpublished	Eine Seite wird von der Website genommen
content.page.route.changed	Eine Seite zieht auf eine neue Adresse um (eine Weiterleitung wird hinzugefügt)
content.entry.published	Ein Collection-Eintrag wird veröffentlicht
content.entry.unpublished	Ein Collection-Eintrag wird von der Website genommen
content.global.published	Header, Footer oder ein anderes Global wird veröffentlicht
content.translation.published	Eine Übersetzung wird veröffentlicht
contract.activated	Ein neuer Site-Contract wird aktiviert
seo.redirects.changed	Weiterleitungen ändern sich
media.asset.uploaded	Eine Mediendatei wird hochgeladen
form.published	Ein Formular wird veröffentlicht
form.submission.accepted	Eine Formular-Einsendung wird angenommen
lead.created	Ein neuer Lead trifft ein (nur IDs, keine personenbezogenen Daten)
lead.merged	Ein Lead wird mit einem anderen zusammengeführt (nur IDs)
bot.published	Ein Chatbot wird veröffentlicht

Atlas wartet bis zu 10 Sekunden auf Ihre Antwort und folgt keinen Weiterleitungen. Nutzen Sie den Zustellverlauf in Studio, um Nutzlasten und Fehler zu prüfen.