Webhook dan purge

Cara kerjanya

Ketika editor menerbitkan, membatalkan penerbitan, memindahkan, me-rollback, atau menghapus entri, atau mengubah sesuatu di seluruh situs seperti menu, tema, atau pengaturan, ATLAS mengantrekan satu POST bertanda tangan untuk setiap webhook aktif milik brand. Situs Anda memeriksa tanda tangan, membuang salinan cache halaman yang terdampak, dan pengunjung berikutnya mendapat konten segar, sekitar satu detik setelah penerbitan.

Tambahkan webhook di Pengaturan, Penerbitan, Hooks. Berikan alamat HTTPS lengkap endpoint Anda dan sebuah secret. URL harus memakai port 443 dan mengarah ke alamat publik. Setiap pengiriman muncul di daftar Pengiriman, tempat pengiriman yang gagal bisa dicoba ulang.

Permintaan

{
  "event": "entry.published",
  "brand": "atlascms",
  "entry": { "id": "01m518vvbf8txh40wcvwhvtzyd", "type": "page", "locale": "en", "path": "/faq" },
  "paths": ["/faq"],
  "at": "2026-10-21T14:42:20+00:00"
}

paths mendaftar path publik yang perlu disegarkan. Perubahan yang memengaruhi seluruh situs (settings.updated, menu.updated, theme.activated, dan sejenisnya) mengirim "paths": ["*"] dan tanpa entry. Purge manual dari Alat, Cache mengirim path yang Anda pilih.

Verifikasi tanda tangan

Tanda tangan adalah HMAC-SHA256 dari string {timestamp}.{raw body} dengan secret webhook Anda, ditulis sebagai heksadesimal. Selalu hitung atas byte body mentah yang Anda terima, sebelum parsing JSON, bandingkan dalam waktu konstan, dan tolak timestamp yang lebih dari lima menit.

import { createHmac, timingSafeEqual } from 'node:crypto'

export function isFromAtlas(rawBody: string, headers: Headers, secret: string): boolean {
  const timestamp = headers.get('x-atlas-timestamp') ?? ''
  const age = Math.abs(Date.now() / 1000 - Number(timestamp))
  if (!Number.isFinite(age) || age > 300) return false

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest()
  const given = Buffer.from((headers.get('x-atlas-signature') ?? '').replace(/^sha256=/, ''), 'hex')
  return given.length === expected.length && timingSafeEqual(given, expected)
}

$timestamp = $_SERVER['HTTP_X_ATLAS_TIMESTAMP'] ?? '';
$given = str_replace('sha256=', '', $_SERVER['HTTP_X_ATLAS_SIGNATURE'] ?? '');
$rawBody = file_get_contents('php://input');

$fresh = abs(time() - (int) $timestamp) <= 300;
$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);

if (! $fresh || ! hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

# Reproduce a signature by hand while you debug
printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

Parse setelah Anda memverifikasi

Membaca body sebagai JSON lalu men-serialisasi-nya lagi bisa mengubah spasi dan urutan key, dan tanda tangan tidak akan cocok lagi. Verifikasi string mentah terlebih dahulu.

Jawab cepat, siap menerima pengulangan

• Kembalikan 2xx apa pun dalam beberapa detik. Kerjakan urusan cache setelah Anda menjawab jika lambat.
• Jawaban lain, atau timeout, dihitung sebagai kegagalan. ATLAS mencoba 5 kali secara total, menunggu 10 detik, 1 menit, 5 menit, dan 15 menit di antara percobaan. Setelah kegagalan kelima, pengiriman ditandai gagal dan admin diberi tahu.
• Pengiriman dilakukan setidaknya sekali. Buat handler Anda aman dijalankan dua kali, dan gunakan X-Atlas-Delivery untuk mengenali pengulangan.
• Gunakan secret berbeda untuk setiap situs. Secret menentukan cache brand mana yang boleh dibersihkan oleh pesan bertanda tangan.

Dengan layer Nuxt

@atlas/nuxt menyediakan endpoint-nya untuk Anda. Arahkan webhook ke https://your-site.example/api/__atlas/purge dan atur secret yang sama di NUXT_ATLAS_PURGE_SECRET. Route memverifikasi tanda tangan dan jendela lima menit, lalu membuang data CMS yang di-cache milik brand itu dan menjawab { "brand", "purged" }. Tanda tangan yang salah atau basi adalah 401. Situs multi-brand memberi setiap host purgeSecret-nya sendiri; lihat panduan layer.