Webhook gửi đi: payload và chữ ký

Webhook gửi đi (outbound webhook) chuyển các cảnh báo, báo cáo theo lịch, tin nhắn thử và bản tóm tắt báo cáo của AutoPSEO tới một endpoint do bạn vận hành, dưới dạng một POST JSON cho mỗi tin nhắn, được ký bằng HMAC-SHA256. Bạn có thể dùng nó để đưa dữ liệu vào Zapier, Make, n8n, một công cụ quản lý sự cố hoặc code của riêng bạn; không cần tài khoản Slack hay Teams. Bạn đang tìm webhook giao bài viết lên website? Webhook đó thuộc về content engine: xem phân phối nội dung.

Thêm webhook

1. Trong mục Outbound webhooks, bấm New webhook.
2. Đặt Name và dán URL của endpoint. URL phải là HTTPS công khai: hệ thống từ chối http thường, localhost, tên miền kết thúc bằng .local hoặc .internal, host không có dấu chấm, cũng như địa chỉ IP riêng hoặc link-local.
3. Sao chép signing secret hiển thị sau khi bạn lưu. Khóa này chỉ hiện đúng một lần.
4. Bấm Send test để gửi một sự kiện test, sau đó gắn báo cáo theo lịch hoặc cảnh báo vào webhook.

Một request webhook trông như thế nào

Mỗi tin nhắn là một POST với các header sau:

Dưới đây là một cảnh báo traffic-drop cho một property dạng domain, từ lượt chạy lúc 06:00 UTC ngày 12 tháng 10 năm 2026, được định dạng để dễ đọc (khi truyền đi, nó là JSON dạng gọn, còn giá trị id và site_id là giá trị giả):

{
  "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"
}

Các trường cấp cao nhất giống nhau với mọi sự kiện:

Các tỷ lệ được biểu diễn dưới dạng phân số: change bằng -0.25 nghĩa là giảm 25%, và ctr bằng 0.034 nghĩa là 3,4%.

Các loại sự kiện

result nhắc lại những gì detector đã đo: fired, metric, value, baseline, change (null khi không có gì để so sánh), severity và summary, cùng với z, tức điểm z hiệu chỉnh, đối với anomaly. totals và previous chứa clicks, impressions, ctr và position cho hai khoảng thời gian của một báo cáo. Mỗi detector đo gì được mô tả tại Cảnh báo.

Cách xác minh chữ ký

Chữ ký là HMAC-SHA256 của chính xác các byte mà AutoPSEO đã gửi, dùng signing secret của webhook làm khóa và được viết dưới dạng sha256= cộng với hex viết thường. Để kiểm tra:

1. Đọc raw body của request trước khi phân tích JSON. Việc phân tích rồi tuần tự hóa lại có thể làm thay đổi các byte.
2. Tính HMAC-SHA256 trên các byte đó, dùng secret ở dạng văn bản: chuỗi 64 ký tự đúng như được hiển thị, không giải mã từ hex.
3. Thêm tiền tố sha256= rồi so sánh kết quả với header X-AutoPSEO-Signature bằng phép so sánh thời gian hằng định.
4. Từ chối request nếu hai giá trị khác nhau. Nếu khớp, hãy trả về mã trạng thái 2xx ngay lập tức và xử lý các việc tốn thời gian sau.

Một bộ nhận cho Node.js, không cần thư viện ngoài:

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

Phép kiểm tra độ dài được đặt trước vì timingSafeEqual của Node sẽ ném lỗi khi hai buffer có độ dài khác nhau.

Quy tắc gửi

• Mỗi tin nhắn chỉ được thử một lần, với thời gian chờ 10 giây. Mọi phản hồi khác 2xx đều bị tính là thất bại và được lưu trong Delivery history cùng mã trạng thái và phần đầu của response body.
• Redirect không được theo dõi. Phản hồi 3xx sẽ thất bại kèm ghi chú yêu cầu dùng URL cuối cùng.
• Không có việc thử lại theo bộ hẹn giờ. Một cảnh báo gửi thất bại không được đánh dấu là đã gửi, nên lần kiểm tra kế tiếp sẽ đánh giá lại và gửi nếu điều kiện vẫn được kích hoạt: sáng hôm sau với đa số detector, giờ kế tiếp với index flip. Một báo cáo theo lịch gửi thất bại sẽ không được gửi lại trong cùng kỳ, vì vậy hãy dùng Send now sau khi sửa endpoint.
• id được tạo cho mỗi request, nên nó định danh một lần gửi chứ không phải một sự kiện. Để loại bỏ cảnh báo trùng lặp, hãy kết hợp event_type, site_url và ngày của occurred_at: một quy tắc chỉ gửi tối đa một lần cho mỗi property trong mỗi ngày UTC, trừ khi có người chạy Test rule.

Signing secret

AutoPSEO hiển thị signing secret một lần duy nhất, khi bạn lưu webhook, và danh sách sẽ không bao giờ hiện lại. Hãy lưu nó vào cấu hình của bộ nhận ngay lập tức, cùng chỗ với endpoint mà nó bảo vệ.

Bản thân URL được lưu dưới dạng mã hóa, và danh sách chỉ hiển thị host cùng vài ký tự cuối. Xóa một webhook cũng xóa mọi quy tắc đang gửi tới webhook đó. Nếu bạn muốn một thẻ dễ đọc trong kênh Teams thay vì JSON, hãy dùng Microsoft Teams.