انتقل إلى المحتوى

Webhooks

الـ webhook في ليڤانت غيت (LevantGit) إشعار آلي: تسجّل عنوان خادمك مرة واحدة، فيصله طلب HTTP يحمل تفاصيل الحدث كلّما وقع في الـ repository push أو issue أو pull request أو release. تحتاجه لربط الـ repository بخدمة خارجية أو بنشر تلقائي. وتشرح هذه الصفحة إضافته، وشكل بياناته، والتحقق من توقيعه.

ما هو الـ webhook؟

الـ webhook رابط تعطيه لليڤانت غيت، فيرسل إليه طلب HTTP كلما وقع حدث في الـ repository: push لـ commits، فتح issue، إنشاء pull request، نشر release، وغيرها. تستخدمه لإعلام فريقك على تطبيق محادثة، أو لتشغيل نشر تلقائي على خادمك، أو لأي ربط مع خدمة خارجية.

إضافة webhook

  1. افتح الـ repository ثم Settings ثم Webhooks. تحتاج صلاحية مدير على الـ repository.
  2. اضغط Add Webhook واختر نوع الوجهة. الأنواع المتاحة: Gitea (طلب عام بصيغة JSON، وهو ما تختاره لخادمك الخاص)، Gogs، Slack، Discord، DingTalk، Telegram، Microsoft Teams، Feishu، WeCom، Packagist.
  3. املأ Target URL وطريقة HTTP ونوع المحتوى، واكتب Secret إن أردت التحقق من مصدر الطلبات، ثم اختر الأحداث التي تريد استقبالها.
  4. احفظ. تجد في صفحة الـ webhook زر Test Delivery وقائمة Recent Deliveries فيها كل طلب مع رده، وهي أفضل مكان لتتبّع الأخطاء.

يمكن إضافة الـ webhook على مستوى الـ organization أيضًا فيشمل كل repositories التابعة لها، من إعدادات الـ organization.

ملاحظة

كل الأحداث تُرسل كطلبات POST (ونوع Gitea يمكنه أيضًا استخدام GET). ويمكنك إضافة Authorization Header تُرسل مع كل طلب إن كان خادمك يطلبها.

شكل البيانات المرسلة

يرسل ليڤانت غيت مع كل حدث ترويسات تحدد نوع الحدث ومعرّف الإرسال، وتُكرَّر بأسماء متوافقة مع GitHub و Gogs لتسهيل إعادة استخدام الأدوات الجاهزة:

X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push

وهذا مثال على payload لحدث push:

{
  "ref": "refs/heads/develop",
  "before": "28e1879d029cb852e4844d9c718537df08844e03",
  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
  "compare_url": "http://localhost:3000/LevantGit/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
  "commits": [
    {
      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
      "message": "Webhooks Yay!",
      "url": "http://localhost:3000/LevantGit/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
      "author": {
        "name": "LevantGit",
        "email": "[email protected]",
        "username": "LevantGit"
      },
      "committer": {
        "name": "LevantGit",
        "email": "[email protected]",
        "username": "LevantGit"
      },
      "timestamp": "2017-03-13T13:52:11-04:00"
    }
  ],
  "repository": {
    "id": 140,
    "owner": {
      "id": 1,
      "login": "LevantGit",
      "full_name": "LevantGit",
      "email": "[email protected]",
      "avatar_url": "https://localhost:3000/avatars/1",
      "username": "LevantGit"
    },
    "name": "webhooks",
    "full_name": "LevantGit/webhooks",
    "description": "",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/LevantGit/webhooks",
    "ssh_url": "ssh://LevantGit@localhost:2222/LevantGit/webhooks.git",
    "clone_url": "http://localhost:3000/LevantGit/webhooks.git",
    "website": "",
    "stars_count": 0,
    "forks_count": 1,
    "watchers_count": 1,
    "open_issues_count": 7,
    "default_branch": "master",
    "created_at": "2017-02-26T04:29:06-05:00",
    "updated_at": "2017-03-13T13:51:58-04:00"
  },
  "pusher": {
    "id": 1,
    "login": "LevantGit",
    "full_name": "LevantGit",
    "email": "[email protected]",
    "avatar_url": "https://localhost:3000/avatars/1",
    "username": "LevantGit"
  },
  "sender": {
    "id": 1,
    "login": "LevantGit",
    "full_name": "LevantGit",
    "email": "[email protected]",
    "avatar_url": "https://localhost:3000/avatars/1",
    "username": "LevantGit"
  }
}

مثال: تشغيل سكربت PHP عند كل push

أضف webhook من نوع Gitea بهذه القيم:

  • Target URL: http://mydomain.com/webhook.php
  • طريقة HTTP: POST
  • نوع المحتوى: application/json
  • Secret: 123
  • التشغيل عند: Push Events
  • نشط: مفعّل

ثم أنشئ على خادمك الملف webhook.php. الـ secret لا يُرسل في الـ payload؛ بل يُستخدم لحساب توقيع HMAC يصل في الترويسة X-Gitea-Signature، وعليك إعادة حسابه ومقارنته:

<?php

$secret_key = '123';

// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
    exit();
}

// get payload
$payload = trim(file_get_contents("php://input"));

if (empty($payload)) {
    error_log('FAILED - no payload');
    exit();
}

// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';

// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);

// check payload signature against header signature
if ($header_signature !== $payload_signature) {
    error_log('FAILED - payload signature');
    exit();
}

// convert json to array
$decoded = json_decode($payload, true);

// success, do something

تنبيه

لا تشغّل أي أمر على خادمك قبل التحقق من التوقيع؛ فرابط الـ webhook علني بطبيعته، وبدون الـ secret يستطيع أي أحد أن يرسل إليه طلبًا مزيّفًا.

ماذا بعد؟

هذه الصفحة مبنية على وثائق Gitea (رخصة MIT) بعد ترجمتها وتبسيطها.