ვებჰუკები

OpenPR იყენებს ვებჰუკებს გარე სისტემების რეალურ დროში შეტყობინებისთვის მდგომარეობის ცვლილებების შესახებ. ყოველი ვებჰუკის მიწოდება ხელმოწერილია HMAC-SHA256-ით, ჩაწერილია webhook_deliveries ცხრილში აუდიტისთვის და მოიცავს მდიდარ კონტექსტუალურ მონაცემებს ქვედა ავტომატიზაციისთვის.

როგორ მუშაობენ ვებჰუკები

1. ხდება მდგომარეობის ცვლილება (ამოცანა შეიქმნა, სპრინტი დაიწყო, წინადადება წარდგენილია და ა.შ.)
2. OpenPR ამოწმებს webhooks ცხრილს სამუშაო სივრცეში აქტიური ვებჰუკებისთვის, რომლებიც ამ მოვლენის ტიპზე არიან გამოწერილი
3. ყოველი შესაბამისი ვებჰუკისთვის იქმნება პეილოადი ერთეულის სრული მონაცემებით
4. პეილოადი ხელმოწერილია ვებჰუკის საიდუმლო გასაღებით HMAC-SHA256-ის გამოყენებით
5. HTTP POST იგზავნება ვებჰუკის URL-ზე ხელმოწერის ჰედერებით
6. მიწოდების შედეგი (სტატუსი, სხეული, ხანგრძლივობა) ჩაიწერება webhook_deliveries-ში

მოვლენების ტიპები

OpenPR ასხივებს 30 მოვლენის ტიპს, ორგანიზებულს შვიდ კატეგორიად.

ამოცანების მოვლენები (5)

მოვლენა	როდის ისვრის
issue.created	ახალი ამოცანა შეიქმნა
issue.updated	ამოცანის ველები შეიცვალა (მოიცავს changes სხვაობას)
issue.assigned	ამოცანის მინიჭებული პირი შეიცვალა (მოიცავს ძველ/ახალ მინიჭებულის ID-ებს)
issue.state_changed	ამოცანის მდგომარეობა შეიცვალა (მოიცავს ძველ/ახალ მდგომარეობას)
issue.deleted	ამოცანა წაიშალა

კომენტარების მოვლენები (3)

მოვლენა	როდის ისვრის
comment.created	ამოცანაზე კომენტარი დაემატა (მოიცავს mentions მასივს)
comment.updated	კომენტარი დარედაქტირდა
comment.deleted	კომენტარი წაიშალა

ლეიბლების მოვლენები (2)

მოვლენა	როდის ისვრის
label.added	ლეიბლი მიმაგრდა ამოცანაზე
label.removed	ლეიბლი ამოიშალა ამოცანიდან

სპრინტის მოვლენები (2)

მოვლენა	როდის ისვრის
sprint.started	სპრინტის სტატუსი შეიცვალა აქტიურზე
sprint.completed	სპრინტი მონიშნულია როგორც დასრულებული

პროექტებისა და წევრების მოვლენები (5)

მოვლენა	როდის ისვრის
project.created	ახალი პროექტი შეიქმნა
project.updated	პროექტის ველები შეიცვალა
project.deleted	პროექტი წაიშალა
member.added	მომხმარებელი დაემატა სამუშაო სივრცეში
member.removed	მომხმარებელი ამოიშალა სამუშაო სივრციდან

მმართველობის მოვლენები (9)

მოვლენა	როდის ისვრის
proposal.created	ახალი წინადადება შეიქმნა
proposal.updated	წინადადების ველები შეიცვალა
proposal.deleted	წინადადება წაიშალა
proposal.submitted	წინადადება წარდგენილია განსახილველად
proposal.voting_started	კენჭისყრა გაიხსნა წინადადებაზე
proposal.archived	წინადადება არქივირებულია
proposal.vote_cast	ხმა მიცემულია წინადადებაზე
veto.exercised	ვეტოს მფლობელმა გამოიყენა ვეტოს უფლება
veto.withdrawn	ვეტო გაუქმდა

ესკალაციისა და აპელაციის მოვლენები (2)

მოვლენა	როდის ისვრის
escalation.started	ესკალაციის პროცესი დაიწყო
appeal.created	აპელაცია შეტანილია გადაწყვეტილების წინააღმდეგ

კონფიგურაციის მოვლენები (1)

მოვლენა	როდის ისვრის
governance_config.updated	მმართველობის კონფიგურაცია შეიცვალა

ხელოვნური ინტელექტის ამოცანების მოვლენები (2)

მოვლენა	როდის ისვრის
ai.task_completed	ხელოვნური ინტელექტის ამოცანა წარმატებით დასრულდა
ai.task_failed	ხელოვნური ინტელექტის ამოცანა ჩავარდა ხელახალი ცდების ამოწურვის შემდეგ

ვებჰუკის კონფიგურაცია

ვებჰუკები კონფიგურირებულია სამუშაო სივრცის მიხედვით API-ის საშუალებით. ყოველი ვებჰუკი მიუთითებს:

ველი	ტიპი	აღწერა
url	string	HTTPS ბოლო წერტილი მოვლენების მისაღებად
secret	string	საზიარო საიდუმლო HMAC-SHA256 ხელმოწერისთვის
events	JSONB	გამოწერილი მოვლენების ტიპების მასივი
active	boolean	ვებჰუკის ჩართვა ან გამორთვა
bot_user_id	UUID (არჩევითი)	თუ დაყენებულია, ჩართავს ბოტის კონტექსტის გამდიდრებას ხელოვნური ინტელექტის ამოცანების გაშვებისთვის

როდესაც bot_user_id დაყენებულია და მოვლენა ეხება ამ ბოტზე მინიჭებულ ამოცანას, პეილოადი მოიცავს bot_context ობიექტს აგენტის გაშვების ინფორმაციით.

პეილოადის სტრუქტურა

ყოველი ვებჰუკის მიწოდება მოიცავს ამ HTTP ჰედერებს:

ჰედერი	მნიშვნელობა
Content-Type	application/json
User-Agent	OpenPR-Webhook/1.0
X-Webhook-Signature	sha256=<hex-კოდირებული HMAC>
X-Webhook-Event	მოვლენის ტიპი (მაგ., issue.created)
X-Webhook-Delivery	მიწოდების უნიკალური UUID

პეილოადის სხეული

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "issue.created",
  "timestamp": "2026-03-18T10:30:00.000Z",
  "workspace": {
    "id": "workspace-uuid",
    "name": "My Workspace"
  },
  "project": {
    "id": "project-uuid",
    "name": "Backend API",
    "key": "IM01"
  },
  "actor": {
    "id": "user-uuid",
    "name": "Admin",
    "email": "admin@example.com",
    "entity_type": "human"
  },
  "data": {
    "issue": {
      "id": "issue-uuid",
      "key": "IM01-A1B2C3D4",
      "title": "Fix authentication flow",
      "description": "The login endpoint returns 500...",
      "state": "todo",
      "priority": "high",
      "assignee_ids": ["bot-uuid"],
      "label_ids": ["label-uuid"],
      "sprint_id": "sprint-uuid",
      "created_at": "2026-03-18T10:30:00.000Z",
      "updated_at": "2026-03-18T10:30:00.000Z"
    }
  },
  "bot_context": {
    "is_bot_task": true,
    "bot_id": "bot-uuid",
    "bot_name": "Claude Agent",
    "bot_agent_type": "claude-code",
    "trigger_reason": "created",
    "webhook_id": "webhook-uuid"
  }
}

ბოტის კონტექსტი

bot_context ველი არსებობს მხოლოდ მაშინ, როდესაც:

1. ვებჰუკს აქვს bot_user_id კონფიგურირებული, და
2. ამოცანა მინიჭებულია ამ ბოტ-მომხმარებელზე, ან
3. ბოტი @მოხსენიებულია კომენტარში

trigger_reason ველი მიუთითებს, რატომ გააქტიურდა ბოტი:

მიზეზი	როდის
created	ამოცანა შეიქმნა ბოტით როგორც მინიჭებული პირი
assigned	ამოცანა მინიჭებულია ან განახლებულია ბოტით როგორც მინიჭებული პირი
status_changed	ამოცანის მდგომარეობა შეიცვალა
mentioned	ბოტი @მოხსენიებულია კომენტარში
completed	ხელოვნური ინტელექტის ამოცანა დასრულდა
failed	ხელოვნური ინტელექტის ამოცანა ჩავარდა

მოვლენის სპეციფიკური მონაცემები

issue.updated, issue.assigned და issue.state_changed მოვლენებისთვის data ობიექტი მოიცავს changes ველს, რომელიც აჩვენებს რა შეიცვალა:

{
  "data": {
    "issue": { "..." : "..." },
    "changes": {
      "state": {
        "old": "todo",
        "new": "in_progress"
      }
    }
  }
}

comment.created მოვლენებისთვის data მოიცავს mentions მასივს მომხმარებლის UUID-ებით:

{
  "data": {
    "comment": { "..." : "..." },
    "issue": { "..." : "..." },
    "mentions": ["user-uuid-1", "user-uuid-2"]
  }
}

ხელმოწერის ვერიფიკაცია

ვებჰუკის მიწოდების დასადასტურებლად, გამოთვალეთ მოთხოვნის სხეულის HMAC-SHA256 თქვენი ვებჰუკის საიდუმლოს გამოყენებით და შეადარეთ X-Webhook-Signature ჰედერში მოცემულ ხელმოწერას.

import hmac
import hashlib

def verify_webhook(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require("crypto");

function verifyWebhook(secret, body, signatureHeader) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

მიწოდების ჩანაწერები

ყოველი ვებჰუკის მიწოდება შენახულია webhook_deliveries ცხრილში:

• მიწოდების UUID
• ვებჰუკის ID
• მოვლენის ტიპი
• სრული პეილოადი (JSONB)
• მოთხოვნის ჰედერები
• პასუხის სტატუს კოდი
• პასუხის სხეული
• შეცდომის შეტყობინება (თუ მიწოდება ჩავარდა)
• ხანგრძლივობა მილიწამებში
• წარმატების ფლაგი
• დროის ნიშანი

ვებჰუკის last_triggered_at დროის ნიშანი განახლდება ყოველი მიწოდების ცდის შემდეგ.

მიწოდების ქცევა

• ტაიმაუტი: 10 წამი თითოეულ მიწოდების ცდაზე
• ავტომატური ხელახალი ცდა არ ხდება: ჩავარდნილი მიწოდებები ჩაიწერება, მაგრამ ხელახლა არ ცდება (ხელოვნური ინტელექტის ამოცანების სისტემას აქვს საკუთარი ხელახალი ცდის მექანიზმი)
• ასინქრონული გაშვება: ვებჰუკები გაეშვება ფონურ Tokio ამოცანაში და არ ბლოკავენ API-ის პასუხს
• საუკეთესო მცდელობის პრინციპი: თუ პეილოადის კონსტრუქცია ჩავარდება, შეცდომა ჩაიწერება და ვებჰუკი გამოტოვდება

დაკავშირებული

• OpenPR მიმოხილვა — არქიტექტურა და სწრაფი დაწყება
• ხელოვნური ინტელექტის ამოცანები — როგორ მართავენ ვებჰუკები ხელოვნური ინტელექტის ამოცანების გაშვებას
• მმართველობა — მმართველობის მოვლენები და კონფიგურაცია
• არქიტექტურის მიმოხილვა — სრული პაიპლაინის კომუნიკაცია