وب‌هوک‌ها

راه‌اندازی

به Settings → API and MCP → Webhooks → Add endpoint بروید، یک آدرس https:// وارد کنید و eventهایی را که می‌خواهید انتخاب کنید. یک secret برای چک کردن امضاها می‌گیرید که فقط یک بار نمایش داده می‌شود.

• با Edit آدرس و eventها را تغییر می‌دهید. secret عوض نمی‌شود.
• Test همان لحظه یک event از نوع ping می‌فرستد تا گیرنده‌تان را تست کنید.
• Log آخرین ارسال‌ها و تعداد تلاش‌های هرکدام را نشان می‌دهد.

Eventها

Event	چه وقت
issue.resolved	بررسی دوباره یا بررسی کامل، مشکل را دیگر پیدا نمی‌کند
issue.reopened	مشکلی که حل شده بود دوباره برگشته
audit.finished	یک بررسی کامل تمام شده (صفحه‌ها، مشکل‌های باز، امتیازها)
score.changed	امتیاز سایت بعد از یک بررسی 2 امتیاز یا بیشتر تغییر کرده
connection.broken	اتصال Google یا WordPress از کار افتاده
recheck.failed	بررسی دوباره اجرا شده و مشکل هنوز هست، اصلاحی که نوشته شده هنوز روی صفحه live نیست، یا خود بررسی دوباره اجرا نشده
write.applied	یک تغییر تأییدشده (فیلد سئو، llms.txt، قوانین خزنده‌های هوش مصنوعی) از طریق WordPress یا اپ Shopify نوشته شده
write.failed	یک تغییر تأییدشده نوشته نشده
write.not_live	بررسی دوباره، مقدار نوشته‌شده را روی صفحه live پیدا نکرده
agentic.finished	اجرای دوباره Agentic browsing تمام شده یا ناموفق بوده

ارسال

POST https://your-endpoint
Content-Type: application/json
User-Agent: MonoRanks-Webhooks/1
X-MonoRanks-Event: recheck.failed
X-MonoRanks-Delivery: <delivery id>
X-MonoRanks-Signature: sha256=<hex>

هر body این فیلدها را دارد: id (همان delivery id)، event، at، workspaceId و siteId. بیشتر eventها host و یک link به صفحه مربوط در اپ را هم دارند.

{
  "id": "…",
  "event": "recheck.failed",
  "at": "2026-10-01T09:12:00.000Z",
  "workspaceId": "…",
  "siteId": "…",
  "issue": { "id": "…", "ruleId": "SEO-ONP-011", "title": "Missing meta description", "severity": "serious", "pages": 3 },
  "crawlId": "…",
  "reason": "still_present",
  "recheck": { "present": 3, "checked": 4 },
  "link": "https://app.monoranks.com/sites/…/issues/…"
}

فیلدهایی که هر event اضافه می‌کند:

• issue.resolved، issue.reopened: issue (id، ruleId، title، severity، pages) و crawlId.
• audit.finished: crawlId، status، pagesCrawled، openIssues و score (site، health، aeo).
• score.changed: from، to، delta و since.
• connection.broken: connection (مثلاً gsc یا wordpress) و error.
• recheck.failed: issue، reason (still_present، not_live یا error) و recheck (present، checked).
• write.applied، write.failed، write.not_live: برای هر دسته تغییر تأییدشده یک event، با batchId، issueIds، source (wordpress یا shopify) و حداکثر 50 مورد در changes که هرکدام url، field، value، status و error دارند. در write.not_live هر تغییر notLiveReason و liveValue (مقداری که صفحه نشان می‌دهد) را هم دارد.
• agentic.finished: jobId، url، strategy، status (done یا failed)، passed از applicable، چک‌های ناموفق در failing و error.

ظرف 20 ثانیه با یک status از نوع 2xx پاسخ بدهید. هر پاسخ دیگری باعث می‌شود ارسال دوباره امتحان شود.

چک کردن امضا

امضا یک HMAC-SHA256 از body خام request است که با secret همان endpoint ساخته می‌شود:

import { createHmac, timingSafeEqual } from 'node:crypto';
const expected = 'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-monoranks-signature']));

همان body خامی را که دریافت کرده‌اید استفاده کنید، نه نسخه‌ای که دوباره serialize شده.