Webhook

Crei i webhook in Studio in Integrations → Webhooks. Ciascuno ha un URL HTTPS, gli eventi che riceve e un segreto di firma che inizia con whsec_, mostrato una sola volta.

Atlas consegna solo a indirizzi HTTPS pubblici. Gli indirizzi di rete privata vengono rifiutati; l’HTTP semplice è consentito solo verso localhost durante lo sviluppo.

Richiesta

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…

Verificare ogni richiesta

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

I controlli, in ordine:

1. Usi il corpo grezzo della richiesta.
2. Rifiuti i timestamp più vecchi di 5 minuti.
3. Calcoli HMAC-SHA256("<t>.<raw body>") con il Suo segreto di firma e lo confronti in tempo costante.
4. Ignori gli id X-Atlas-Delivery ripetuti.

Registri nei log il tipo di evento e l’id di consegna, mai il corpo né il segreto.

Eventi

Il corpo della richiesta è il payload dell’evento. Per content.page.published è { "pageId", "route", "revision" }. Il tipo di evento si trova nell’intestazione X-Atlas-Event.

I webhook si configurano una sola volta, in Sviluppo, e ricevono anche gli eventi del sito web online. Ogni payload ha environment: "development" o "production", così può distinguerli.

Evento	Quando
content.page.published	Una pagina viene pubblicata o ripristinata
content.page.unpublished	Una pagina viene rimossa dal sito web
content.page.route.changed	Una pagina passa a un nuovo indirizzo (viene aggiunto un reindirizzamento)
content.entry.published	Una voce di raccolta viene pubblicata
content.entry.unpublished	Una voce di raccolta viene rimossa dal sito web
content.global.published	Vengono pubblicati l’intestazione, il piè di pagina o un altro contenuto globale
content.translation.published	Viene pubblicata una traduzione
contract.activated	Viene attivato un nuovo contratto del sito
seo.redirects.changed	I reindirizzamenti cambiano
media.asset.uploaded	Viene caricato un file multimediale
form.published	Viene pubblicato un modulo
form.submission.accepted	Viene accettato un invio di un modulo
lead.created	Arriva un nuovo contatto commerciale (solo id, nessun dato personale)
lead.merged	Un contatto viene unito a un altro (solo id)
bot.published	Viene pubblicato un chatbot

Atlas attende fino a 10 secondi la Sua risposta e non segue i reindirizzamenti. Usi la cronologia delle consegne di Studio per ispezionare payload ed errori.