وبهوک‌های گیت‌هاب: چرا بیشتر تیم‌ها از قدرت واقعی آن بی‌خبرند؟

وبهوک‌های گیت‌هاب (GitHub Webhooks) مکانیزمی سبک و قدرتمند برای اطلاع‌رسانی خودکار رویدادهای مخزن به سرویس‌های خارجی هستند که در پروژه‌های مدرن، پایه اتوماسیون CI/CD، اعلان‌ها و یکپارچگی با ابزارهای ثالث را تشکیل می‌دهند.

در پروژه‌های متعددی که اتوماسیون زیرساخت را برای تیم‌ها راه‌اندازی کرده‌ام، متوجه شده‌ام که وبهوک‌ها اغلب به‌عنوان یک ابزار جانبی دیده می‌شوند، در حالی که می‌توانند ستون اصلی جریان‌های خودکار باشند. تفاوت بنیادی وبهوک با Polling در این است که وبهوک، مدل Push دارد: به‌جای اینکه سرویس خارجی هر چند ثانیه از GitHub بپرسد «چیز جدیدی هست؟»، GitHub در لحظه وقوع رویداد، خبر را Push می‌کند. این تغییر پارادایم، تأخیر را از چند دقیقه به چند صد میلی‌ثانیه کاهش می‌دهد و بار روی زیرساخت را به‌شدت کم می‌کند. این نوشتار، وبهوک‌های گیت‌هاب را از مفاهیم پایه تا الگوهای پیشرفته بررسی می‌کند.

وبهوک، یک تماس تلفنی است از سمت GitHub که می‌گوید «همین حالا این اتفاق افتاد». Polling، تماس مکرر شماست که می‌پرسد «چیزی افتاده؟». تفاوت در کارایی، چشمگیر است.

وبهوک چیست و چه تفاوتی با API و Polling دارد؟

وبهوک (Webhook)، یک درخواست HTTP POST است که سیستم مبدأ (در اینجا GitHub) در واکنش به یک رویداد، به URL مشخصی ارسال می‌کند. این URL، توسط سیستم مقصد تعریف می‌شود. Webhook در ویکی‌پدیا مرور تاریخی و فنی این مفهوم را ارائه می‌دهد.

تفاوت وبهوک و API

API، مدل Pull دارد. کلاینت درخواست می‌فرستد و پاسخ می‌گیرد. وبهوک، مدل Push دارد. سرور درخواست می‌فرستد و کلاینت پاسخ می‌دهد. این تفاوت ظریف، پیامدهای معماری عمیقی دارد.

تفاوت وبهوک و Polling

در Polling، کلاینت هر چند ثانیه از سرور می‌پرسد «خبر جدیدی هست؟». این روش، ساده اما ناکارآمد است. وبهوک، رویدادمحور است و تنها در لحظه وقوع، اطلاع‌رسانی می‌کند.

کاربردهای رایج وبهوک در گیت‌هاب

• اطلاع‌رسانی به Slack، Discord و Teams
• راه‌اندازی دیپلوی خودکار روی سرور
• به‌روزرسانی سیستم‌های مدیریت پروژه
• ایندکس مجدد مستندات
• ارسال داده به سیستم‌های تحلیل
• هماهنگی با سیستم‌های CI/CD خارجی

در هم‌روندی در گیت‌هاب اکشنز به الگوهای خودکارسازی داخلی گیت‌هاب اشاره کرده‌ام که می‌توانند با وبهوک ترکیب شوند. Zapier یا Make؛ کدام برای اتوماسیون بهتر است؟ نیز به ابزارهای بیرونی اتوماسیون اشاره دارد.

معماری وبهوک در گیت‌هاب

درک معماری داخلی وبهوک، برای استفاده حرفه‌ای ضروری است.

ثبت وبهوک

وبهوک را می‌توان در سه سطح ثبت کرد:

• سطح Repository: فقط رویدادهای یک مخزن.
• سطح Organization: رویدادهای همه مخازن سازمان.
• سطح GitHub App: رویدادهای همه مخازنی که اپ به آن‌ها دسترسی دارد.

ساختار Payload

Payload وبهوک، یک JSON است که ساختار آن به نوع رویداد بستگی دارد. مثال ساده از وبهوک push:

{
  "ref": "refs/heads/main",
  "before": "9f4d5c6a...",
  "after": "1a2b3c4d...",
  "repository": {
    "id": 123456,
    "name": "my-repo",
    "full_name": "owner/my-repo"
  },
  "pusher": {
    "name": "developer",
    "email": "dev@example.com"
  },
  "commits": [
    {
      "id": "1a2b3c4d...",
      "message": "fix: resolve login issue",
      "timestamp": "2026-01-01T12:00:00Z",
      "author": {
        "name": "Developer"
      }
    }
  ]
}

هدرهای HTTP

هر درخواست وبهوک، شامل هدرهای مهمی است:

• X-GitHub-Event: نوع رویداد (مثلاً push، pull_request).
• X-GitHub-Delivery: شناسه یکتای تحویل.
• X-Hub-Signature-256: امضای HMAC برای اعتبارسنجی.
• User-Agent: معمولاً GitHub-Hookshot.

حداکثر زمان انتظار

GitHub به مقصد وبهوک حدود ۱۰ ثانیه فرصت پاسخ می‌دهد. اگر در این زمان پاسخی نگیرد، تحویل ناموفق ثبت می‌شود. این محدودیت، طراحی سیستم مقصد را تحت تأثیر قرار می‌دهد.

سیاست Retry

اگر مقصد پاسخ ۲xx ندهد، GitHub تلاش مجدد را در بازه‌های مشخص انجام می‌دهد. تعداد تلاش‌ها محدود است و پس از چند بار ناموفق، تحویل به‌عنوان شکست نهایی ثبت می‌شود.

Deliveries Log

GitHub برای هر وبهوک، یک لاگ از Deliveries ارائه می‌دهد. این لاگ، شامل Payload، Headerها، کد پاسخ و زمان تحویل است. برای دیباگ، ابزار اصلی همین لاگ است.

رویدادهای مهم و کاربرد آن‌ها

GitHub ده‌ها نوع رویداد پشتیبانی می‌کند. در این بخش، مهم‌ترین‌ها را بررسی می‌کنم.

رویداد Push

پرکاربردترین رویداد. پس از هر push موفق به مخزن ارسال می‌شود. شامل اطلاعات شاخه، کامیت‌ها و فایل‌های تغییریافته. این رویداد، پایه دیپلوی خودکار است. CI/CD برای پروژه‌های وردپرسی چگونه پیاده‌سازی می‌شود؟ نمونه عملی ارائه می‌دهد. گیت در توسعه وردپرس راهنمای حرفه‌ای نیز به این موضوع می‌پردازد.

رویداد Pull Request

برای CI، بازبینی خودکار و اعلان. این رویداد در چند زیر‌رویداد (opened، synchronize، closed) ارسال می‌شود. Pull Request در GitHub راهنمای حرفه‌ای به بهترین رویه‌ها اشاره دارد.

رویداد Issues

برای هماهنگی تیم و مدیریت کارها. مدیریت پروژه با GitHub Projects: راهنمای عملی از راه‌اندازی تا بلوغ تیمی به یکپارچگی با سیستم‌های مدیریتی اشاره دارد.

رویداد Release

برای انتشار نسخه و اطلاع‌رسانی. این رویداد در زمان‌بندی‌های خاص ارزشمند است.

رویداد Workflow Run

برای زنجیره‌سازی جریان‌ها. اگر یک GitHub Actions تمام شود، می‌تواند وبهوکی ارسال کند که جریان دیگری را راه بیندازد.

رویداد Ping

هنگام ثبت وبهوک جدید، GitHub یک رویداد Ping ارسال می‌کند. این رویداد، برای تست اتصال و اعتبارسنجی استفاده می‌شود.

امنیت وبهوک‌ها

وبهوک، یک درخواست HTTP از اینترنت است. اگر امن نشود، هر کسی می‌تواند درخواست جعلی بفرستد.

Secret و HMAC

هنگام ثبت وبهوک، یک Secret تعریف می‌کنید. GitHub از این Secret برای تولید HMAC-SHA256 از Payload استفاده می‌کند و آن را در هدر X-Hub-Signature-256 قرار می‌دهد. سرویس مقصد باید همین محاسبه را انجام دهد و مقایسه کند.

// Node.js example
const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret);
  const digest = "sha256=" + hmac.update(payload).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(signature)
  );
}

HTTPS اجباری

وبهوک باید به یک URL با HTTPS ارسال شود. ارسال به HTTP، Payload را در معرض شنود قرار می‌دهد. SSL و HTTPS چه نقشی در امنیت دارند؟ به اهمیت این لایه اشاره دارد.

اعتبارسنجی Delivery ID

هر تحویل، یک شناسه یکتا در هدر X-GitHub-Delivery دارد. ذخیره این شناسه و بررسی تکراری نبودن آن، از حملات Replay جلوگیری می‌کند.

IP Whitelisting

GitHub محدوده IP مشخصی برای وبهوک‌ها دارد. با محدود کردن دسترسی به این IPها، لایه امنیتی دیگری اضافه می‌شود. لیست IPها در مستندات GitHub منتشر می‌شود.

Rate Limiting

سرویس مقصد باید Rate Limiting داشته باشد تا در برابر حملات DoS مقاوم باشد. حمله DDoS (Distributed Denial of Service) چیست و چگونه دفع می‌شود؟ به این موضوع می‌پردازد.

Idempotency

از آنجا که GitHub ممکن است یک وبهوک را چند بار ارسال کند (Retry)، سرویس مقصد باید Idempotent باشد. یعنی پردازش چندباره یک رویداد، وضعیت را خراب نکند. آسیب‌پذیری IDOR چیست و چگونه رفع می‌شود؟ به مفاهیم مشابه امنیتی اشاره دارد.

پیاده‌سازی عملی

پیاده‌سازی وبهوک، از سمت GitHub و سمت مقصد انجام می‌شود.

ثبت وبهوک در GitHub

در تنظیمات مخزن، بخش Webhooks، روی Add webhook کلیک کنید و موارد زیر را تنظیم کنید:

• Payload URL: آدرس مقصد
• Content type: application/json (توصیه‌شده)
• Secret: یک رشته تصادفی طولانی
• SSL verification: enabled
• Events: انتخاب رویدادها

پردازش وبهوک در سرور

یک مثال ساده با Express.js:

const express = require("express");
const crypto = require("crypto");

const app = express();
const SECRET = process.env.GITHUB_WEBHOOK_SECRET;

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-hub-signature-256"];
  const hmac = crypto.createHmac("sha256", SECRET);
  const digest = "sha256=" + hmac.update(req.body).digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature))) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.headers["x-github-event"];
  const payload = JSON.parse(req.body.toString());

  if (event === "push" && payload.ref === "refs/heads/main") {
    triggerDeploy(payload);
  }

  res.status(200).send("OK");
});

app.listen(3000);

الگوی Queue و Async Processing

پردازش وبهوک باید سریع باشد (کمتر از ۱۰ ثانیه). اگر پردازش طولانی است، Payload را در یک صف (Redis، RabbitMQ) قرار دهید و بلافاصله پاسخ ۲۰۰ بدهید. Workerها، پردازش را به‌صورت Async انجام می‌دهند.

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  verifySignature(req);
  await queue.add("github-event", {
    event: req.headers["x-github-event"],
    payload: req.body.toString()
  });
  res.status(200).send("OK");
});

الگوی Serverless

توابع Serverless مانند AWS Lambda، Vercel Functions و Cloudflare Workers، گزینه‌های عالی برای وبهوک هستند. هزینه پایین، مقیاس‌پذیری خودکار و نگهداری کم. معماری سرورلس چیست و چه کاربردی دارد؟ به این معماری اشاره دارد.

درون‌سازمانی: از وبهوک به Teams

یک کاربرد رایج، ارسال وبهوک به Microsoft Teams یا Slack است. Slack یا Microsoft Teams؛ کدام برای تیم شما بهتر است؟ مقایسه‌ای عملی ارائه می‌دهد.

دیباگ و عیب‌یابی

دیباگ وبهوک، مهارتی ضروری است.

Deliveries Log

در تنظیمات وبهوک، بخش Recent Deliveries، لاگ کامل هر تحویل را نشان می‌دهد: Payload، Headerها، کد پاسخ و زمان. این لاگ، ابزار اول دیباگ است.

Redeliver

GitHub امکان Redeliver هر وبهوک را فراهم می‌کند. اگر پردازش مقصد با خطا مواجه شد، می‌توانید همان Payload را دوباره ارسال کنید.

ابزارهای محلی

برای دیباگ محلی، از ابزارهایی مانند ngrok یا smee.io استفاده کنید که یک URL عمومی موقت ایجاد می‌کنند و درخواست‌ها را به سرور محلی شما تونل می‌زنند.

ngrok http 3000

بررسی امضا

یکی از رایج‌ترین خطاها، عدم تطابق امضا است. مطمئن شوید که:

• Secret درست تنظیم شده.
• Payload بدون تغییر به تابع HMAC پاس داده می‌شود (raw body).
• الگوریتم sha256 استفاده می‌شود.

خطاهای رایج

• Timeout: پردازش بیش از ۱۰ ثانیه طول می‌کشد.
• کد پاسخ اشتباه: پاسخ ۳xx یا ۴xx که GitHub را به Retry وامی‌دارد.
• Body Parse نادرست: اگر body قبل از محاسبه HMAC پردازش شود، امضا تطابق نمی‌کند.
• Content-Type اشتباه: اگر form-encoded انتخاب شود، Payload ساختار متفاوتی دارد.

مقیاس‌پذیری و الگوهای پیشرفته

در سازمان‌های بزرگ، وبهوک‌ها می‌توانند به صدهزار رویداد در روز برسند. مقیاس‌پذیری، چالش اصلی است.

الگوی Fan-out

یک وبهوک واحد دریافت کنید و سپس آن را به چند سرویس مقصد ارسال کنید. این الگو، از ثبت چند وبهوک تکراری در GitHub جلوگیری می‌کند.

الگوی Dead Letter Queue

اگر پردازش یک رویداد شکست بخورد، آن را به یک صف جداگانه (DLQ) منتقل کنید. این کار، از دست رفتن داده جلوگیری می‌کند.

الگوی Idempotency Key

از X-GitHub-Delivery به‌عنوان Idempotency Key استفاده کنید. در دیتابیس، یک رکورد برای هر تحویل ثبت کنید و از پردازش تکراری جلوگیری کنید.

الگوی Rate Limiting

محدود کردن نرخ پردازش، از فشار ناگهانی جلوگیری می‌کند. به‌خصوص در زمان‌هایی که چند رویداد همزمان می‌رسند.

الگوی Multi-Tenant

در SaaS، هر مشتری ممکن است وبهوک جداگانه داشته باشد. معماری باید Multi-Tenant باشد و مسیریابی بر اساس مخزن یا سازمان انجام شود.

مکانیزم Retry در سمت مقصد

اگر سرویس مقصد، وابسته به سرویس دیگری است که موقتاً در دسترس نیست، باید Retry داخلی داشته باشد. الگوی Exponential Backoff، استاندارد طلایی است.

وبهوک و GraphQL

برخی سازمان‌ها از GitHub GraphQL API برای دریافت اطلاعات بیشتر پس از دریافت وبهوک استفاده می‌کنند. این ترکیب، انعطاف بالایی می‌دهد. GraphQL یا REST؟ راهنمای انتخاب برای پروژه‌های واقعی به این موضوع می‌پردازد. REST API در عمل: راهنمای ساخت، تست و نگهداری نیز مقایسه‌ای عملی ارائه می‌دهد.

وبهوک و Zero Trust

در معماری Zero Trust، هر درخواست باید اعتبارسنجی شود. وبهوک‌ها نیز از این قاعده مستثنا نیستند. HMAC، IP Whitelist و Rate Limiting، لایه‌های این اعتبارسنجی هستند.

مقایسه وبهوک با GitHub Actions

یکی از پرتکرارترین پرسش‌ها این است که چه زمانی از وبهوک و چه زمانی از GitHub Actions استفاده کنیم.

چه زمانی وبهوک؟

وقتی هدف، اطلاع‌رسانی یا هماهنگی با سرویس خارجی است. وقتی کنترل کامل روی محیط اجرا لازم است. وقتی سرویس مقصد، خارج از GitHub اجرا می‌شود.

چه زمانی GitHub Actions؟

وقتی کار، در محیط گیت‌هاب قابل انجام است. وقتی هزینه و نگهداری اهمیت دارد. وقتی از اکوسیستم Actions استفاده می‌کنید. GitHub Actions راهنمای خودکارسازی گردش کار به این موضوع می‌پردازد.

ترکیب هر دو

در بسیاری از پروژه‌ها، بهترین رویکرد ترکیب است: GitHub Actions برای CI/CD داخلی، وبهوک برای هماهنگی با سرویس‌های خارجی. بهترین ابزارهای CI/CD؛ کدام برای پروژه شما مناسب است؟ مقایسه جامعی ارائه می‌دهد. GitLab برای تیم‌های DevOps: راهنمای کامل از CI/CD تا امنیت و انتشار نیز به این ترکیب اشاره دارد.

مقایسه با هوک‌های سمت سرور سنتی

هوک‌های سمت سرور Git سنتی، روی سرور مخزن اجرا می‌شوند. وبهوک، نسخه ابری و مدرن این مفهوم است. هوک‌های سمت سرور در گیت‌هاب: چرا بیشتر تیم‌ها پتانسیل امنیتی و اتوماسیون آن را نادیده می‌گیرند؟ و هوک‌های سمت کلاینت در گیت‌هاب به این دو مکانیزم اشاره دارند.

اشتباهات رایج

• نبود Secret: وبهوک بدون Secret، در معرض جعل است.
• نادیده گرفتن HMAC: اعتبارسنجی امضا، ضروری است.
• پردازش همگام طولانی: بیش از ۱۰ ثانیه، منجر به Timeout می‌شود.
• نبود Idempotency: پردازش تکراری، وضعیت را خراب می‌کند.
• کد پاسخ اشتباه: پاسخ ۴xx یا ۵xx باعث Retry و فشار مضاعف می‌شود.
• نبود لاگ: بدون لاگ، دیباگ دشوار است.
• وبهوک بیش از حد: ثبت چند وبهوک تکراری برای یک رویداد.
• نادیده گرفتن SSL verification: غیرفعال کردن SSL verification، امنیت را نابود می‌کند.
• نبود Rate Limiting: سرویس مقصد در برابر بار زیاد آسیب‌پذیر می‌شود.

در رفع خطاهای رایج Git راهنمای کاربردی به خطاهای مشابه اشاره کرده‌ام. اشتباهات رایج امنیت وب (Web Security) کدامند؟ نیز به این موضوع می‌پردازد. GitHub یا GitLab؛ کدام برای توسعه‌دهندگان بهتر است؟ نیز به تفاوت‌های ابزارها اشاره دارد. تفاوت GitHub و GitLab و انتخاب برای مدیریت پروژه نیز مقایسه‌ای عملی ارائه می‌دهد.

پرسش‌های پرتکرار درباره وبهوک‌های گیت‌هاب

وبهوک گیت‌هاب چیست؟

یک درخواست HTTP POST است که GitHub در واکنش به رویدادهای مخزن (push، pull request، issue و...) به یک URL مشخص ارسال می‌کند تا سرویس‌های خارجی از وقایع مطلع شوند.

تفاوت وبهوک و API چیست؟

API مدل Pull دارد (کلاینت درخواست می‌فرستد). وبهوک مدل Push دارد (سرور درخواست می‌فرستد). وبهوک، تأخیر کم و بار سرور پایین دارد.

چگونه امنیت وبهوک را تأمین کنیم؟

با تعریف Secret و اعتبارسنجی HMAC-SHA256، استفاده از HTTPS، IP Whitelisting، Rate Limiting و Idempotency.

اگر سرویس مقصد پاسخ ندهد چه می‌شود؟

GitHub چند بار تلاش مجدد می‌کند. اگر همه تلاش‌ها شکست بخورد، تحویل به‌عنوان ناموفق ثبت می‌شود. می‌توانید از بخش Recent Deliveries، Redeliver کنید.

حداکثر زمان پردازش وبهوک چقدر است؟

حدود ۱۰ ثانیه. اگر پردازش طولانی‌تر است، Payload را در صف قرار دهید و بلافاصله پاسخ ۲۰۰ بدهید.

آیا وبهوک می‌تواند جایگزین GitHub Actions شود؟

خیر، این دو مکمل یکدیگرند. وبهوک برای هماهنگی با سرویس‌های خارجی، GitHub Actions برای CI/CD داخلی گیت‌هاب.

چگونه وبهوک را در محیط محلی تست کنیم؟

با ابزارهایی مانند ngrok یا smee.io که یک URL عمومی موقت ایجاد می‌کنند و درخواست‌ها را به سرور محلی تونل می‌زنند.

چه رویدادهایی از گیت‌هاب وبهوک ارسال می‌کنند؟

ده‌ها رویداد مختلف از جمله push، pull_request، issues، release، workflow_run، deployment_status و ping.

آیا وبهوک‌ها برای پروژه‌های کوچک هم مناسب‌اند؟

بله. وبهوک برای هر اندازه پروژه مفید است. حتی یک مخزن شخصی می‌تواند از وبهوک برای اطلاع‌رسانی یا بکاپ خودکار استفاده کند.

وبهوک‌های گیت‌هاب، پل میان مخزن و اکوسیستم ابزارهای بیرونی هستند. اگر تجربه‌ای در پیاده‌سازی وبهوک دارید، به‌خصوص اگر با چالش امنیتی یا مقیاس‌پذیری مواجه شده‌اید، آن را در دیدگاه‌ها بنویسید. تجربه شما می‌تواند راهنمای دیگران باشد. 🔗⚙️