# Webhooks والتكاملات

ادفع أحداث الحوكمة إلى أدواتك، وتصرّف في Azoth من Slack أو Microsoft Teams.

## Webhooks الحوكمة

أضف نقطة نهاية HTTPS — أداة GRC أو ITSM، أو SIEM — في **الإعدادات › التكاملات والتنبيهات › Webhooks**، ثم حدّد الأحداث التي تتلقاها:

- `decision.blocked` — خُتم قرار بنتيجة حظر
- `derogation` — إعفاء من قاعدة سياسة، أو إعفاء من اختبار الفريق الأحمر، أو قراءة للقانون: طُلب أو مُنح أو رُفض أو أُلغي
- `proof.broken` — وجد التحقق الذي يجري كل ساعة أن سلسلة مساحة العمل منقطعة

> معرّفات ورموز وبصمات فقط: لا محتوى، ولا أسماء، ولا نص حر. والمستقبِل الذي يحتاج إلى المزيد يستعلم من واجهة API بمفتاحه الخاص (`GET /api/v1/journal`).

```
{
  "id": "<delivery uuid>",
  "event": "decision.blocked",
  "workspace_id": "<workspace>",
  "created_at": "<iso date>",
  "data": { "seq": 1042, "entryHash": "<sha256>", "decision": "blocked_by_policy", "traceId": "…" }
}
```

## التحقق من التوقيع

يحمل كل تسليم `X-Azoth-Event`، و`X-Azoth-Delivery` — ثابت عبر إعادات المحاولة، فأزِل التكرار بناءً عليه — و`X-Azoth-Timestamp` و`X-Azoth-Signature: t=<timestamp>,v1=<hex>`، وهو HMAC-SHA256 بسرّ التوقيع الخاص بنقطة النهاية على `<timestamp>.<raw body>`.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAzothWebhook(rawBody, header, secret, toleranceSecs = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.floor(Date.now() / 1000) - t > toleranceSecs) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(parts.v1, 'hex'), b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

// In a route handler: read the RAW body before parsing it.
export async function POST(req) {
  const body = await req.text();
  if (!verifyAzothWebhook(body, req.headers.get('x-azoth-signature') ?? '', process.env.AZOTH_WEBHOOK_SECRET)) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }
  const event = JSON.parse(body);   // deduplicate on event.id (= X-Azoth-Delivery)
  return Response.json({ ok: true });
}
```

يُختم القرار أولًا. ويُعاد التسليم الفاشل مع مهلة متزايدة، خمس مرات على الأكثر؛ ونقطة النهاية التي تُزال قبل التسليم تُسقط أحداثها المعلّقة.

## Slack

- اسأل Azoth عبر `/azoth <question>` أو رسالة مباشرة: المحرك نفسه الذي يشغّل المساعد داخل التطبيق، بهويتك ودورك. وتصلك الإجابة وحدك، ولا تُنشر أبدًا في قناة.
- يتلقى المالكون والمسؤولون المرتبطون بالمصادقة متعددة العوامل (MFA) الموافقات والإعفاءات التي تنتظرهم ويبتّون فيها بنقرة — يُقرأ الدور لحظة النقر، ويُفرض مبدأ العينين الأربع، ويُختم القرار. أما تغيير دور، أو تغيير مدة الاحتفاظ، أو إعفاء الفريق الأحمر، فيُفتح دائمًا في Azoth.
- اربط حسابك عبر `/azoth link`.

## روبوت Microsoft Teams

- تسجّل كل مؤسسة روبوتها الخاص ذا المستأجر الواحد. ويُشفَّر سرّه ويُتحقق منه لدى Microsoft قبل حفظه، ويبني Azoth حزمة تطبيقه.
- يُجاب عن الأسئلة في محادثتك الفردية مع الروبوت بهويتك؛ وتصل الموافقات والإعفاءات في شكل بطاقات إلى المالكين والمسؤولين المرتبطين بالمصادقة متعددة العوامل، ويُبتّ فيها وفق القواعد نفسها المتبعة في Slack.

## PagerDuty وقنوات التنبيه

يذهب كل تنبيه في مساحة العمل — الموافقات المنتظرة، والحوكمة، وحالات تسجيل الدخول الشاذة، وانقطاعات المزوّدين، وتغييرات النماذج، وحلقات الوكلاء الموقوفة، وحصة القرارات المختومة — إلى مسارات التنبيه في **الإعدادات › التكاملات والتنبيهات › التنبيهات**: PagerDuty (مع إزالة التكرار)، أو Webhooks قنوات Slack أو Teams، أو البريد الإلكتروني، كلٌّ ابتداءً من الحد الأدنى للخطورة الذي يحدده. تذهب عتبات الميزانية إلى الوجهات المحددة مع كل ميزانية.

## تطبيق GitHub

- ثبّت تطبيق GitHub من **الإعدادات › التكاملات والتنبيهات** واختر مستودعاته: يحصل كل طلب سحب على مستودع مفعَّل على فحص (check run). ويحصل المستودع المرتبط بمجموعة اختبارات انحدار على نتيجة كل حالة؛ تُنشأ المجموعات عبر واجهة البرمجة (`POST /api/v1/regression/suites`) ولا توجد بعد شاشة تربط مجموعة — لاختبار طلبات السحب اليوم، شغّل مجموعة في CI الخاص بك باستخدام [CLI](https://www.azothos.ai/ar/docs/cli#ci).
- يقرأ التطبيق نفسه بصمة الذكاء الاصطناعي في مستودع بمجرد تفعيلك القراءة لذلك المستودع ([الإثراءات](https://www.azothos.ai/ar/docs/enrichments#footprint)).
