وب‌هوک‌ها (Webhooks)

وب‌هوک‌ها به شما امکان می‌دهند انتگریشن‌هایی بسازید که به رویدادهای مخازن گیتی‌یار شما پاسخ می‌دهند. وقتی رویدادی اتفاق می‌افتد (مثل push یا ایجاد مسئله)، گیتی‌یار یک HTTP POST payload به URL پیکربندی‌شده ارسال می‌کند.

ایجاد وب‌هوک

مراحل

1. به تنظیمات مخزن → وب‌هوک‌ها بروید
2. روی "افزودن وب‌هوک" کلیک کنید
3. نوع وب‌هوک را انتخاب کنید:
   • گیتی‌یار - برای نمونه‌های گیتی‌یار/Gitea
   • Gogs - برای نمونه‌های Gogs
   • Slack - اعلان‌های Slack
   • Discord - اعلان‌های Discord
   • Dingtalk - اعلان‌های Dingtalk
   • Telegram - ربات Telegram
   • Microsoft Teams - اعلان‌های Teams
   • سفارشی - هر HTTP endpoint
4. تنظیمات وب‌هوک را پیکربندی کنید
5. روی "ایجاد" کلیک کنید

رویدادهای وب‌هوک

رویدادهای مخزن

• push - Git push به مخزن
• create - branch یا tag ایجاد شد
• delete - branch یا tag حذف شد
• fork - مخزن fork شد
• release - انتشار منتشر شد

رویدادهای مسئله

• issues - مسئله باز، بسته، دوباره باز شد
• issue_comment - کامنت روی مسئله

رویدادهای درخواست تغییر

• pull_request - PR باز، بسته، merge، sync شد

رویدادهای ویکی

• wiki - صفحه ویکی ایجاد، ویرایش، حذف شد

پیکربندی وب‌هوک

تنظیمات پایه

URL: Endpoint که payload های وب‌هوک را دریافت می‌کند

https://your-server.com/webhook

نوع محتوا: فرمت payload

• application/json - فرمت JSON (توصیه می‌شود)
• application/x-www-form-urlencoded - فرم انکود شده

Secret: Secret اختیاری برای تأیید payload

سرور شما باید header X-Gitea-Signature را با استفاده از HMAC-SHA256 تأیید کند.

تأیید SSL: تأیید گواهی‌های SSL

• برای production فعال کنید
• فقط برای testing غیرفعال کنید

احراز هویت پایه HTTP: افزودن احراز هویت

username:password

تنظیمات Trigger

کدام رویدادها؟:

• فقط رویداد push - فقط روی push ها trigger می‌شود
• همه را برای من بفرست - تمام رویدادها
• بگذارید رویدادهای خاص انتخاب کنم - رویدادهای خاص را انتخاب کنید

فعال: فعال یا غیرفعال کردن وب‌هوک

تست وب‌هوک‌ها

تست دستی

1. به تنظیمات وب‌هوک بروید
2. روی "تحت تحویل" → "Push" کلیک کنید
3. تاریخچه تحویل را برای نتایج بررسی کنید

مشاهده تاریخچه تحویل

1. جزئیات وب‌هوک را باز کنید
2. لیست تحویل‌های اخیر را ببینید
3. روی تحویل کلیک کنید برای مشاهده:
   • Header های درخواست
   • Payload درخواست
   • Header های پاسخ
   • بدنه پاسخ
   • کد وضعیت پاسخ
   • مدت زمان

مثال‌های Payload

رویداد Push

{
  "secret": "your-secret",
  "ref": "refs/heads/main",
  "before": "6113c5d64f9c8b4e7f2e4a7b3d1c9e5f8a2b4c6d",
  "after": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "commits": [
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
      "message": "افزودن ویژگی جدید",
      "url": "http://localhost:3000/user/repo/commit/a1b2c3d4",
      "author": {
        "name": "جان دو",
        "email": "john@example.com"
      }
    }
  ],
  "repository": {
    "id": 1,
    "name": "my-repo",
    "full_name": "user/my-repo",
    "url": "http://localhost:3000/user/my-repo"
  },
  "pusher": {
    "name": "user",
    "email": "user@example.com"
  }
}

امنیت وب‌هوک

تأیید Payload ها

همیشه امضاهای وب‌هوک را تأیید کنید:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

بهترین شیوه‌ها

• ✅ همیشه از HTTPS در production استفاده کنید
• ✅ Secret قوی تنظیم کنید
• ✅ امضاها را تأیید کنید
• ✅ Payload ها را اعتبارسنجی کنید
• ✅ خطاها را به‌طور مناسب مدیریت کنید
• ✅ منطق retry پیاده‌سازی کنید
• ✅ تحویل‌های وب‌هوک را log کنید

موارد استفاده رایج

انتگریشن CI/CD

Trigger ساخت‌ها روی push:

from flask import Flask, request
import subprocess

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # تأیید امضا
    # پردازش payload
    
    # Trigger ساخت
    subprocess.run(['./build.sh'])
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=5000)

اعلان‌های Slack

ارسال پیام به کانال Slack:

import requests

def notify_slack(message):
    url = "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    
    payload = {
        "text": f"Push جدید به مخزن: {message}"
    }
    
    requests.post(url, json=payload)

ردیابی مسئله

ایجاد تیکت در سیستم‌های خارجی:

def create_jira_issue(payload):
    # استخراج اطلاعات مسئله
    # ایجاد تیکت در Jira
    # لینک برگشت به گیتی‌یار
    pass

عیب‌یابی

مسائل رایج

وب‌هوک fire نمی‌شود:

• بررسی کنید وب‌هوک فعال است
• trigger های رویداد را تأیید کنید
• بررسی کنید URL قابل دسترسی است

خطای 404:

• تأیید کنید URL صحیح است
• اطمینان حاصل کنید endpoint وجود دارد
• routing را بررسی کنید

خطای 401/403:

• احراز هویت را بررسی کنید
• اعتبارنامه‌ها را تأیید کنید
• کنترل‌های دسترسی را بررسی کنید

خطای 500:

• log های سرور را بررسی کنید
• مدیریت payload را بررسی کنید
• مدیریت خطا را بررسی کنید

نکات Debug

• از تاریخچه تحویل وب‌هوک استفاده کنید
• برای توسعه محلی از ابزارهایی مثل ngrok تست کنید
• تمام وب‌هوک‌های ورودی را log کنید
• از سرویس‌های تست وب‌هوک استفاده کنید

مراحل بعدی

• درباره API بیاموزید
• Git LFS را کاوش کنید
• درباره مهاجرت بخوانید