مستندات توسعه دهندگان
وب هوک ها
ده 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های جدید را اضافه کنید.