تخطي إلى المحتوى الرئيسي

خطافات الويب

تتيح خطافات الويب (Webhooks) للكنيسة إرسال إشعارات فورية إلى أدوات الطرف الثالث، مثل منصات الأتمتة (Zapier وMake وn8n)، وأنظمة إدارة العلاقات مع المتبرعين والأعضاء، وأنظمة المحاسبة، أو أي خدمة تقبل طلبات HTTP POST. عندما يتغيّر شخص أو مجموعة أو أسرة في B1، يرسل B1 حمولة JSON موقّعة إلى كل عنوان URL مشترك في ذلك الحدث.

قبل أن تبدأ

  • يحتاج مسؤول الكنيسة الذي يملك صلاحية تعديل إعدادات الكنيسة إلى تسجيل خطافات الويب وإدارتها
  • يجب أن يكون نقطة الاستقبال لديك متاحةً عبر HTTPS على عنوان عام
  • احرص على وجود طريقة آمنة لحفظ المفتاح السري للتوقيع، فهو يُعرض مرة واحدة فقط

نظرة عامة​

خطافات الويب صادرة فقط: يستدعي B1 نقطة الاستقبال لديك، ولا تستدعي أنت B1. كل خطاف ويب هو اشتراك خاص بالكنيسة يتكوّن من عنوان URL للوجهة، ومفتاح سري للتوقيع، وقائمة بالأحداث المشترك فيها.

يعتمد التسليم على صندوق صادر متين: عند وقوع حدث مشترك فيه، يسجّل B1 صفاً للتسليم، ويرسله عامل خلفي عبر طلب POST خلال دقيقة تقريباً. تُعاد محاولات التسليم الفاشلة باستخدام تراجع أُسّي (exponential backoff). ولا تضيع أي بيانات إذا كان التسليم بطيئاً أو إذا تعطّلت نقطة الاستقبال لديك لفترة قصيرة.

تسجيل خطاف ويب​

في B1Admin​

انتقل إلى الإعدادات ← المطوّر ← Webhooks ← خطاف ويب جديد. أدخل اسماً، وعنوان URL للحمولة، ثم اختر الأحداث التي تريد الاشتراك فيها. عند الحفظ، يُعرض المفتاح السري للتوقيع مرة واحدة فقط، فانسخه فوراً واحفظه مع تكاملك. لن يُعرض مرة أخرى (يمكنك تدويره لاحقاً، لكن لا يمكنك استرجاع القيمة الأصلية).

عبر الواجهة البرمجية (API)​

جميع نقاط النهاية تقع تحت مسار وحدة العضوية الأساسي /membership/webhooks وتتطلب إما رمز JWT من مسؤول كنيسة يملك صلاحية Settings / Edit، أو مفتاح API أُنشئ بالنطاق settings:write. تقبل المسارات نفسها كلا النوعين من المصادقة. وهذا ما يتيح لـ Zapier وMake تسجيل خطافات الويب نيابةً عن الكنيسة عند تشغيل Zap أو سيناريو.

POST /membership/webhooks
Authorization: Bearer <jwt>
Content-Type: application/json

{
"name": "Zapier — new members",
"url": "https://hooks.zapier.com/hooks/catch/123/abc",
"events": ["person.created", "person.updated", "group.member.added"]
}

تتضمن استجابة الإنشاء — وفقط استجابة الإنشاء — الحقل secret:

{
"id": "a1b2c3d4e5f",
"name": "Zapier — new members",
"url": "https://hooks.zapier.com/hooks/catch/123/abc",
"events": ["person.created", "person.updated", "group.member.added"],
"active": true,
"secret": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822c"
}
الطريقة والمسارالغرض
GET /membership/webhooksعرض خطافات ويب الكنيسة (دون المفتاح السري)
GET /membership/webhooks/eventsقائمة أسماء الأحداث الصالحة
GET /membership/webhooks/:idتحميل خطاف ويب واحد
POST /membership/webhooksالإنشاء (بدون id) أو التحديث (مع id)
POST /membership/webhooks/:id/regenerate-secretتدوير المفتاح السري للتوقيع؛ يعيد القيمة الجديدة مرة واحدة
DELETE /membership/webhooks/:idحذف خطاف ويب
GET /membership/webhooks/:id/deliveriesأحدث محاولات التسليم لخطاف ويب
GET /membership/webhooks/deliveries/:deliveryIdالحمولة الكاملة والاستجابة لعملية تسليم واحدة
POST /membership/webhooks/deliveries/:deliveryId/redeliverإعادة جدولة عملية تسليم

قائمة الأحداث​

تتبع أسماء الأحداث النمط {entity}.{action}. احصل على القائمة الحالية من GET /membership/webhooks/events.

الحدثيُطلق عندما
person.createdتتم إضافة شخص
person.updatedيتم تغيير سجل شخص
person.destroyedيتم حذف شخص
household.createdتتم إضافة أسرة
household.updatedيتم تغيير أسرة
household.destroyedيتم حذف أسرة
group.createdتتم إضافة مجموعة
group.updatedيتم تغيير مجموعة
group.destroyedيتم حذف مجموعة
group.member.addedيُضاف شخص إلى مجموعة
group.member.removedيُزال شخص من مجموعة
donation.createdيُسجَّل تبرع — بالإدخال اليدوي، أو عبر الإنترنت، أو عند الانتقال من حالة معلّق إلى مكتمل
donation.updatedيتم تعديل سجل تبرع
attendance.recordedيُسجَّل حضور (بالإدخال اليدوي أو عبر تسجيل الوصول)
session.createdيتم إنشاء جلسة حضور جديدة (يدوياً أو تلقائياً عند أول تسجيل وصول)
form.submission.createdيتم إرسال نموذج
event.createdتتم إضافة حدث إلى التقويم
event.updatedيتم تعديل حدث في التقويم
event.destroyedيتم حذف حدث من التقويم

تنسيق الحمولة​

كل عملية تسليم هي طلب HTTP من نوع POST يحتوي على جسم بصيغة JSON وهذه الترويسات:

الترويسةالوصف
Content-Typeدائماً application/json
X-B1-Eventاسم الحدث، مثل person.created
X-B1-Delivery-Idمعرّف فريد لمحاولة التسليم هذه — استخدمه لإزالة التكرار
X-B1-Signatureتوقيع HMAC-SHA256 للجسم الخام (انظر أدناه)
X-B1-Timestampالوقت المرسَل فيه الطلب بصيغة Unix (بالثواني)
User-AgentB1-Webhooks/1.0

يغلّف الجسم المورد الذي تغيّر داخل مظروف بسيط:

{
"event": "person.created",
"churchId": "AbC123XyZ90",
"occurredAt": "2026-05-17T14:32:08.114Z",
"data": {
"id": "Pq7Rs2Tu4Vw",
"churchId": "AbC123XyZ90",
"name": { "display": "Jordan Rivera", "first": "Jordan", "last": "Rivera" },
"contactInfo": { "email": "jordan@example.com" }
}
}

بالنسبة إلى أحداث *.destroyed، يحتوي الحقل data على id وchurchId للسجل المحذوف فقط.

تحمل الأحداث التي تشير حمولاتها إلى سجلات أخرى بالمعرّف أيضاً أسماءً مقروءة، تُحلّ وقت التسليم: الحقلان personName وgroupName في أحداث عضوية المجموعة، والحقل personName في أحداث الحضور والتبرع وعضوية القوائم، والحقل groupName في session.created، والحقل formName (بالإضافة إلى personName عندما يكون الإرسال مرتبطاً بشخص) في form.submission.created.

أنواع الموصّلات​

صيغة التسليم الافتراضية هي مظروف JSON أعلاه — أي connectorType: "standard". أما بالنسبة إلى Slack وDiscord، فإن محرك خطافات الويب نفسه يرسل بدلاً من ذلك رسالة بشكل المحادثة تقبلها هاتان الخدمتان مباشرة:

قيمة connectorTypeالجسم المرسلمتى تستخدمه
"standard" (الافتراضي)مظروف {event, churchId, occurredAt, data} موقّععندما تكتب تكاملك الخاص، أو توجّهه إلى Zapier / Make / خادم مخصص
"slack"{ "text": "💝 New donation: $50.00" }عندما ترسل مباشرة إلى عنوان URL لـ Slack Incoming Webhook
"discord"{ "content": "💝 New donation: $50.00" }عندما ترسل مباشرة إلى عنوان URL لخطاف قناة Discord
"mailchimp"غير متاح — الموصّل يستدعي واجهة Mailchimp البرمجية بنفسهعندما تريد مزامنة الجمهور دون عنوان URL تستضيفه

يُحدَّد نوع الموصّل من القائمة المنسدلة Connector Type في محرر خطاف الويب، أو عبر connectorType في جسم POST /membership/webhooks. لا تزال ترويسة X-B1-Signature الموقّعة تُرسل مع عمليات تسليم Slack وDiscord (وهما تتجاهلانها دون ضرر)، لذا فإن التحويل لاحقاً إلى standard لا يتطلب إعادة توقيع.

تُعد Slack وDiscord مجرد إعادة تشكيل للجسم؛ إذ يرسل المحرك ما يزال إلى عنوان URL الذي توفره الكنيسة. أما mailchimp فهو أول موصّل يتولى بنفسه تبادل HTTP الخاص به: لكل حدث، يُرسل طلبات مصادَقاً عليها لإضافة/تحديث/أرشفة/وسم عبر واجهة Mailchimp البرمجية (MailchimpConnector.deliver)، وتُخزَّن بياناته الاعتمادية ({apiKey, audienceId}) مشفّرة بخوارزمية AES في webhooks.connectorConfig، وتكون للكتابة فقط عبر الواجهة البرمجية. لا تقبل خطافات Mailchimp إلا أحداث الشخص وعضوية المجموعة وعضوية القائمة، ويتحقق مسار الحفظ من المفتاح والجمهور لدى Mailchimp قبل القبول. تحفظ صفوف التسليم المظروف القياسي، لذا يُظهر سجل التسليم ما رآه B1 مع استجابة Mailchimp. أما الحالات غير المعيّنة (شخص بلا بريد إلكتروني، أو حدث بلا تعيين) فتُكمل بنجاح مع نص استجابة يبدأ بـ Skipped: بدلاً من استهلاك المحاولات.

عمليات التسليم التجريبية​

يحتوي كل محرر خطاف ويب على زر Send Test Event، ويقابله استدعاء الواجهة البرمجية POST /membership/webhooks/:id/test. يبني مسار الاختبار حمولة اصطناعية للحدث المشترك فيه الأول، ويرسلها فوراً عبر مسار التسليم الموقّع الحقيقي (ومن خلال formatForConnector بالنسبة إلى Slack وDiscord)، ويعيد صف التسليم الناتج متضمناً responseStatus وresponseBody. استخدمه للتأكد من الاتصال ومعالجة التوقيع قبل تفعيل التكامل فعلياً. أما بالنسبة إلى خطافات mailchimp، فيتحقق الاختبار بدلاً من ذلك من بيانات الاعتماد المخزَّنة لدى واجهة Mailchimp البرمجية (لأن الحدث الاصطناعي سيكتب مشتركاً وهمياً في الجمهور الحقيقي للكنيسة)، ويعيد نتيجة بشكل التسليم دون إنشاء صف.

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

تحقّق دائماً من X-B1-Signature قبل الوثوق بأي حمولة. التوقيع هو sha256= متبوعاً بقيمة HMAC-SHA256 بالترميز السداسي عشري للـجسم الخام للطلب، مُفتاحةً بمفتاحك السري للتوقيع. احسب التوقيع على البايتات التي استلمتها — ولا تُعِد تسلسل كائن JSON المحلَّل.

Node.js

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hashlib, hmac

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

PHP

function isValid(string $rawBody, string $signatureHeader, string $secret): bool {
$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
return hash_equals($expected, $signatureHeader ?? "");
}

ارفض أي طلب لا يتطابق توقيعه. يمكنك أيضاً، اختيارياً، رفض الطلبات التي يزيد عمر X-B1-Timestamp فيها على بضع دقائق، للحد من نافذة إعادة التشغيل.

دعم SDK​

بالنسبة إلى Node.js، يوفّر الحزمة @churchapps/integration-sdk أداة تحقق مُكتوبة بأنواع البيانات، وبرمجية وسيطة (middleware) لـ Express تتولى عنك التقاط الجسم الخام، والتحقق من التوقيع، وتحليل المظروف:

import express from "express";
import { b1WebhookMiddleware } from "@churchapps/integration-sdk";

const app = express();
// Capture the raw body before JSON parsing — required so the signature still verifies.
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));

app.post("/webhooks/b1", b1WebhookMiddleware({ secret: process.env.B1_WEBHOOK_SECRET! }), (req, res) => {
const env = req.b1Webhook!;
switch (env.event) {
case "donation.created": console.log("new gift", env.data.amount); break;
}
res.sendStatus(200);
});

يوفّر SDK أيضاً الدالة WebhookVerifier.verify(secret, rawBody, signatureHeader) لبيئات التشغيل غير Express (مثل الدوال بلا خادم، أو Fastify وغيرها). راجع الحزمة على npm للمزيد.

التسليم وإعادة المحاولة​

ينبغي أن ترد نقطة الاستقبال لديك برمز حالة 2xx بأسرع ما يمكن — ويفضَّل أن يكون ذلك بعد وضع العمل في قائمة الانتظار فقط، لا بعد معالجته. يُعدّ أي رد غير 2xx، أو فشل في الاتصال، أو رد يستغرق أكثر من 10 ثوانٍ، عملية تسليم فاشلة.

تُعاد محاولات التسليم الفاشلة باستخدام تراجع أُسّي — 16 محاولة على مدى نحو 5 أيام. تبدأ الفترة من دقيقة واحدة، ثم تمتد إلى ساعات، وصولاً إلى فجوات مدتها 3 أيام للمحاولات الأخيرة. بعد المحاولة الفاشلة السادسة عشرة، تُوسَم عملية التسليم بالحالة exhausted وتُهمل.

التسليم مرة واحدة على الأقل (at-least-once): قد تصل عملية التسليم أكثر من مرة (على سبيل المثال، إذا نجحت نقطة الاستقبال لديك لكن الرد ضاع). استخدم ترويسة X-B1-Delivery-Id لإزالة التكرار — عالج كل معرّف مرة واحدة فقط، واعتبر التكرارات بلا أثر.

التعطيل التلقائي​

إذا أنتج خطاف ويب ثلاث عمليات تسليم متتالية بالحالة exhausted، يعطّله B1 تلقائياً. أصلح نقطة الاستقبال لديك، ثم أعد تفعيل خطاف الويب من B1Admin (أو عبر POST /membership/webhooks مع "active": true).

الفحص وإعادة التسليم​

يعرض محرر خطاف الويب في B1Admin جدولاً باسم Recent Deliveries يتضمن الحدث، والحالة، وعدد المحاولات، ورمز الاستجابة، والطابع الزمني. عند اختيار صف، تظهر الحمولة الكاملة التي أُرسلت والاستجابة التي عادت.

استخدم Redeliver لإعادة جدولة أي عملية تسليم سابقة بحمولتها الأصلية — وهذا مفيد بعد إصلاح خلل في نقطة الاستقبال لديك، أو لاستعادة أحداث فاتتها أثناء تعطّلها.

متطلبات عنوان URL​

بما أن عناوين URL لخطافات الويب توفّرها الكنيسة، يفرض B1 ضوابط حماية من تزوير الطلبات من جانب الخادم (SSRF). يُرفض عنوان URL لخطاف الويب — عند التسجيل، ويُعاد التحقق منه قبل كل عملية تسليم — إذا:

  • لم يكن يستخدم https
  • كان يشير إلى localhost أو اسم مضيف بالنطاق .local / .internal، أو
  • كان يُحلّ إلى عنوان IP خاص، أو loopback، أو link-local، أو خاص ببيانات تعريف السحابة (cloud metadata)

يجب أن تكون نقطة الاستقبال لديك خدمة HTTPS عامة يمكن الوصول إليها.