Webhook keluar: payload dan tanda tangan

Webhook keluar mengirimkan peringatan, laporan terjadwal, pesan uji, dan ringkasan laporan dari AutoPSEO ke endpoint yang Anda kelola, berupa satu POST JSON per pesan yang ditandatangani dengan HMAC-SHA256. Gunakan webhook ini untuk menyuplai Zapier, Make, n8n, alat penanganan insiden, atau kode Anda sendiri; tidak diperlukan akun Slack maupun Teams. Mencari webhook yang mengirimkan artikel ke situs Anda? Itu bagian dari mesin konten: lihat pengiriman konten.

Menambahkan webhook

1. Di bagian Outbound webhooks, klik New webhook.
2. Beri Name dan tempelkan URL endpoint. URL harus berupa HTTPS publik: http biasa, localhost, nama berakhiran .local atau .internal, host tanpa titik, serta alamat IP privat atau link-local akan ditolak.
3. Salin signing secret yang ditampilkan setelah Anda menyimpan. Secret ini hanya ditampilkan satu kali ini.
4. Klik Send test untuk mengirim event test, lalu kaitkan laporan terjadwal atau peringatan ke webhook tersebut.

Seperti apa permintaan webhook

Setiap pesan berupa POST dengan header berikut:

Berikut peringatan penurunan traffic untuk properti domain dari proses pukul 06:00 UTC pada 12 Oktober 2026, diformat agar mudah dibaca (saat dikirim berupa JSON ringkas, dan nilai id serta site_id hanyalah contoh):

{
  "id": "9b2e61f04c3a4d7e8f15a0b6c2d39e47",
  "event_type": "traffic_drop",
  "severity": "high",
  "site_id": "4f0c1e9a2b7d4c58",
  "site_url": "sc-domain:example.com",
  "occurred_at": "2026-10-12T06:00:04.183Z",
  "title": "Traffic drop: example.com",
  "text": "Clicks 1,500 vs 2,000 in the previous window (-25.0%).",
  "url": "https://app.autopseo.com/property/sc-domain%3Aexample.com",
  "payload": {
    "fields": [
      { "label": "Metric", "value": "clicks" },
      { "label": "Current", "value": "1,500" },
      { "label": "Baseline", "value": "2,000" },
      { "label": "Window", "value": "7 days (2026-10-05 → 2026-10-11 vs 2026-09-28 → 2026-10-04)" },
      { "label": "Change", "value": "-25.0%" }
    ],
    "table": null,
    "detector": "traffic_drop",
    "window": 7,
    "range": { "start": "2026-10-05", "end": "2026-10-11", "compStart": "2026-09-28", "compEnd": "2026-10-04" },
    "result": {
      "fired": true,
      "metric": "clicks",
      "value": 1500,
      "baseline": 2000,
      "change": -0.25,
      "severity": "high",
      "summary": "Clicks 1,500 vs 2,000 in the previous window (-25.0%)."
    }
  },
  "source": "autopseo"
}

Kolom tingkat atas sama untuk setiap event:

Rasio berupa pecahan: change bernilai -0.25 berarti turun 25%, dan ctr bernilai 0.034 berarti 3,4%.

Jenis event

result mengulang apa yang diukur oleh detektor: fired, metric, value, baseline, change (null bila tidak ada pembanding), severity, dan summary, ditambah z, yaitu modified z-score, untuk anomaly. totals dan previous berisi clicks, impressions, ctr, dan position untuk dua rentang waktu pada laporan. Apa yang diukur setiap detektor dijelaskan di Alerts.

Cara memverifikasi tanda tangan

Tanda tangan adalah HMAC-SHA256 dari byte persis yang dikirim AutoPSEO, dengan kunci berupa signing secret webhook, ditulis sebagai sha256= plus heksadesimal huruf kecil. Cara memeriksanya:

1. Baca isi permintaan mentah sebelum diurai sebagai JSON. Mengurai lalu menserialisasi ulang dapat mengubah byte-nya.
2. Hitung HMAC-SHA256 atas byte tersebut, dengan secret dipakai sebagai teks: string 64 karakter persis seperti yang ditampilkan, bukan hasil dekode dari heksadesimal.
3. Tambahkan awalan sha256= lalu bandingkan hasilnya dengan header X-AutoPSEO-Signature secara constant-time.
4. Tolak permintaan jika keduanya berbeda. Jika cocok, segera balas dengan status 2xx dan kerjakan proses yang lambat setelahnya.

Contoh penerima untuk Node.js tanpa dependensi:

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.AUTOPSEO_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);
    const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(raw).digest('hex'));
    const received = Buffer.from(String(req.headers['x-autopseo-signature'] || ''));
    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(204).end();
    const event = JSON.parse(raw.toString('utf8'));
    console.log(event.event_type, event.severity, event.site_url);
  });
}).listen(8080);

Pemeriksaan panjang dilakukan lebih dulu karena timingSafeEqual milik Node melempar error ketika panjang kedua buffer berbeda.

Aturan pengiriman

• Setiap pesan hanya dicoba satu kali dengan batas waktu 10 detik. Respons selain 2xx dianggap gagal dan disimpan di Delivery history beserta kode status dan awal isi respons Anda.
• Redirect tidak diikuti. Respons 3xx dianggap gagal dengan catatan untuk memakai URL akhir.
• Tidak ada percobaan ulang berdasarkan timer. Peringatan yang gagal tidak ditandai sebagai terkirim, sehingga pada pemeriksaan berikutnya peringatan itu dievaluasi lagi dan dikirim bila masih terpicu: keesokan paginya untuk sebagian besar detektor, jam berikutnya untuk index flip. Laporan terjadwal yang gagal tidak dikirim ulang pada periode yang sama, jadi gunakan Send now setelah endpoint diperbaiki.
• id dibuat per permintaan, sehingga mengidentifikasi satu pengiriman, bukan satu event. Untuk menghilangkan duplikat peringatan, gabungkan event_type, site_url, dan tanggal dari occurred_at: satu aturan mengirim paling banyak sekali per properti per hari UTC, kecuali seseorang menjalankan Test rule.

Signing secret

AutoPSEO menampilkan signing secret satu kali, saat Anda menyimpan webhook, dan daftar webhook tidak akan menampilkannya lagi. Simpan secret bersama konfigurasi penerima Anda segera, di samping endpoint yang dilindunginya.

URL itu sendiri disimpan terenkripsi, dan daftar hanya menampilkan host serta beberapa karakter terakhirnya. Menghapus webhook juga menghapus semua aturan yang mengirim ke webhook tersebut. Untuk kartu yang mudah dibaca di kanal Teams alih-alih JSON, gunakan Microsoft Teams.