Webhooks

在 Studio 的 Integrations → Webhooks 下建立 Webhook。每個 Webhook 都有一個 HTTPS URL、它接收的事件，以及以 whsec_ 開頭的簽署密鑰（只會顯示一次）。

Atlas 只會傳送到公開的 HTTPS 位址。私人網路位址會被拒絕；僅在開發期間允許以純 HTTP 傳送到 localhost。

請求

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…

驗證每個請求

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

檢查依序為：

1. 使用原始請求本文。
2. 拒絕時間戳記超過 5 分鐘的請求。
3. 以您的簽署密鑰計算 HMAC-SHA256("<t>.<raw body>")，並以恆定時間比較。
4. 忽略重複的 X-Atlas-Delivery ID。

請記錄事件類型與遞送 ID，切勿記錄本文或密鑰。

事件

請求本文即為事件的內容。對於 content.page.published，內容為 { "pageId", "route", "revision" }。事件類型位於 X-Atlas-Event 標頭。

Webhook 只需在 Development 中設定一次，也會接收來自正式網站的事件。每筆內容都有 environment："development" 或 "production"，讓您可以區分兩者。

事件	時機
content.page.published	頁面被發布或還原
content.page.unpublished	頁面從網站下架
content.page.route.changed	頁面移到新位址（會新增重新導向）
content.entry.published	集合項目被發布
content.entry.unpublished	集合項目從網站下架
content.global.published	頁首、頁尾或其他全域內容被發布
content.translation.published	翻譯被發布
contract.activated	新的網站合約被啟用
seo.redirects.changed	重新導向變更
media.asset.uploaded	媒體檔案被上傳
form.published	表單被發布
form.submission.accepted	表單送出被接受
lead.created	新的潛在客戶抵達（僅含 ID，無個人資料）
lead.merged	潛在客戶被合併到另一筆（僅含 ID）
bot.published	聊天機器人被發布

Atlas 最多等待您的回應 10 秒，且不會跟隨重新導向。請使用 Studio 的遞送歷史記錄檢查內容與失敗情況。