مستندات توسعه دهندگان

وب هوک ها

ده event، یک body از نوع JSON و یک امضای HMAC برای چک کردن. برای فرستادن پیام به Slack، باز کردن تیکت یا به روز کردن داشبورد خودتان همین کافی است.

راه اندازی

به Settings → Developer access → 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 روی سایت نوشته شده
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. eventهای مربوط به سایت 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، crawlId، reason (still_present، not_live یا error) و recheck (present، checked). وقتی reason برابر error است، بررسی دوباره اجرا نشده: error دلیلش را می گوید و recheck برابر null است.
  • write.applied، write.failed، write.not_live: برای هر دسته تغییر تأییدشده یک event، با batchId، issueIds، source (فعلاً wordpress)، changesTotal و حداکثر 50 مورد در changes که هرکدام id، issueId، url، field، value (حداکثر 1,000 کاراکتر)، status و error دارند. در write.not_live هر تغییر notLiveReason و liveValue (مقداری که صفحه نشان می دهد) را هم دارد.
  • agentic.finished: jobId، url، strategy، status (done یا failed)، testedAt، passed از applicable، چک های ناموفق در failing (id، title، detail) و error.
  • ping (دکمه Test): فقط message، بدون siteId.

چک کردن امضا

امضا یک 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']));

سؤال های رایج

اگر endpoint من از دسترس خارج باشد چه می شود؟

ارسال ناموفق بعد از 1، 5، 15 و 60 دقیقه دوباره امتحان می شود؛ در کل پنج بار. بعد از 20 خطای پشت سر هم، endpoint غیرفعال می شود. هر ارسال در header X-MonoRanks-Delivery یک id دارد تا بتوانید ارسال های تکراری را کنار بگذارید.

می شود بر اساس سایت فیلتر کرد؟

id سایت (siteId) و معمولاً host آن در body هست؛ فیلتر را سمت خودتان انجام دهید. endpointها برای کل فضای کاری تعریف می شوند.

endpoint را قبل از اضافه شدن eventهای جدید ساخته ام. آن ها را هم دریافت می کنم؟

نه. هر endpoint فقط eventهایی را می گیرد که برایش تیک زده اید. endpoint را ویرایش کنید و eventهای جدید را اضافه کنید.