أحداث الشريك
أحداث موقّعة من خادمك تخبر قُرب خلال ثوانٍ من يحق له البقاء في مجتمعك، وما اسمه وبريده وصورته.
لماذا أحداث وليس سؤالاً عند كل زيارة
قُرب لا يتصل بموقعك أبداً. أنت ترسل كل تغيير لحظة حفظه، ولقطة ليلية تصلح أي شيء فات. هكذا يبقى موقعك المرجع الوحيد دون أن يتوقف المجتمع على عمل موقعك.
الطلب
عنوان واحد لكل مجتمع. المحتوى JSON، والترويسات الثلاث webhook-* وفق مواصفة Standard Webhooks.
POST https://community.example.com/api/webhooks/inbound/{communityId}/host
content-type: application/json
webhook-id: evt_6f1c2a… # = the body's "id", the same on every retry
webhook-timestamp: 1791808447 # unix seconds, fresh on every try
webhook-signature: v1,K3x0…= # one "v1,…" per secret, space-separated
{
"id": "evt_6f1c2a…",
"type": "access.changed",
"created_at": "2026-10-12T09:15:02.418Z",
"community": "{communityId}",
"data": { "sub": "yourorg_9b1e…", "state_version": 1791808447123, "access": "blocked" }
}التوقيع
وقّع النص id.timestamp.body بخوارزمية HMAC-SHA256 باستخدام سر الأحداث بعد فك ترميز base64 لما يلي البادئة whsec_، وأرسله بترميز base64 مسبوقاً بـ v1,. أي مكتبة Standard Webhooks تفعل ذلك تماماً.
import { createHmac } from 'node:crypto'
// secret = "whsec_<base64>": sign with the DECODED bytes after the prefix
const key = Buffer.from(secret.slice('whsec_'.length), 'base64')
const signature = 'v1,' + createHmac('sha256', key)
.update(`${id}.${timestamp}.${body}`) // body = the exact bytes you send
.digest('base64')- وقّع البايتات التي ترسلها كما هي. احفظ المحتوى مرة واحدة، ولا تعِد بناءه من حقوله عند إعادة المحاولة.
- استخدم طابعاً زمنياً جديداً في كل محاولة؛ يرفض قُرب ما يبعد أكثر من 5 دقائق عن ساعته. وأبقِ المعرّف نفسه، فتُطبَّق إعادة المحاولة مرة واحدة.
- أثناء تبديل السر، وقّع بالسرّين معاً: قيمتان v1 بينهما مسافة. يقبل قُرب التطابق مع أي سر ما زال لديه.
أنواع الأحداث
كل حدث عن عضو يحمل sub — المعرّف نفسه الذي أرسلته في externalUserId — وstate_version.
| النوع | data | ما يفعله قُرب |
|---|---|---|
access.changed | sub, state_version, access | «blocked»: تنتهي كل جلسات العضو فوراً ويُرفض دخوله. «allowed»: يستطيع الدخول من جديد دون خطوة موافقة. |
member.session_revoked | sub, state_version, reason | ينهي كل جلسات العضو في قُرب أياً كان الإصدار. أرسله بعد استعادة كلمة المرور أو تغيير البريد لديك. |
member.updated | sub, state_version, name, email, avatar_url | يستبدل اسم العضو وبريده وصورته في مجتمعك. |
member.deleted | sub, state_version, requested_at | طلب حذف معتمد: تُمحى بيانات العضو الشخصية في المجتمع ويُنسى الربط. لا رجعة فيه. |
access.snapshot | snapshot_id, generated_at, page, pages, members[] | القائمة الكاملة لحسابات أعضائك كل ليلة، على صفحات. الأعضاء الذين يعرفهم قُرب ولا يظهرون في لقطة مكتملة يُحظرون. |
ping | message | لا يغيّر شيئاً. استخدمه لاختبار العنوان والسر والتوقيع. |
state_version: الأحدث هو الذي يُعتمد
الردود
رمز الحالة يحدد ما يفعله العامل لديك بعدها. ومع كل رفض رمز ثابت في المحتوى.
| الحالة | المعنى | ماذا تفعل |
|---|---|---|
| 200 | قُبل. | علّمه مُسلَّماً. |
| 400 | الحدث غير سليم: HOST_EVENT_INVALID، أو HOST_EVENT_ID_MISMATCH (المعرّف يختلف عن ترويسة webhook-id)، أو HOST_EVENT_COMMUNITY_MISMATCH. | لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ. |
| 401 | WEBHOOK_SIGNATURE_INVALID: سر خاطئ، أو محتوى تغيّر، أو طابع زمني يبعد أكثر من 5 دقائق. | لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ. |
| 404 | WEBHOOK_PROVIDER_UNKNOWN: معرّف مجتمع خاطئ، أو لم يُعيَّن له سر أحداث بعد. | لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ. |
| 429 | طلبات كثيرة: أكثر من دفعة 500 بمعدل 50 في الثانية. | أعد المحاولة مع تباعد. |
| 500 / 503 | عطل مؤقت لدى قُرب (503 HOST_EVENT_NOT_YET_SUPPORTED: نوع حدث أحدث لا يطبّقه قُرب بعد). | أعد المحاولة مع تباعد. |
ومحتوى الرد 200 يخبر بما حدث: applied (طُبّق)، أو duplicate (مكرر)، أو stale (إصدار أقدم)، أو unknown_member (لم يدخل هذا الشخص المجتمع قط، فلا شيء يُفعل)، أو ignored (تُجوهل).
الإرسال
- مهلة 10 ثوانٍ لكل محاولة.
- تباعد 1 دقيقة ← 5 دقائق ← 30 دقيقة ← ساعتان ← 6 ساعات ← 12 ساعة ← 24 ساعة، ثم كل 24 ساعة، لمدة 72 ساعة إجمالاً. بعدها أوقف الحدث جانباً ونبّه شخصاً.
- مُرسِل واحد لكل حدث: احجز الصفوف حتى لا يرسل عاملان الحدث نفسه.
- لا تحويلات: رد 3xx يعني إعداداً خاطئاً، وليس انتقالاً.
اكتب الحدث في نفس العملية مع التغيير
member.updated
استبدال كامل: أرسل كل حقل تشاركه في كل مرة. الحقل المحذوف يعني أنه فارغ.
- name: بحد أقصى 200 حرف.
- email: إن حُذف أو كان مستخدماً في حساب آخر على قُرب، يبقى للعضو عنوان بديل. لا تُدمج الحسابات أبداً.
- avatar_url: عبر https على المنفذ 443 فقط. يجلب قُرب الصورة مرة واحدة (JPEG أو PNG أو WebP، بحد أقصى 2 ميغابايت)، ويعيد ترميزها بمقاس 512 بكسل ويحفظ نسخته الخاصة. وإن فشل الجلب تبقى الصورة السابقة.
- أرسله فقط والعضو يملك حق الدخول. لا سبب لخروج بيانات شخصية من موقعك عن شخص لا يستطيع الدخول.
access.snapshot
مرة كل ليلة، أرسل القائمة الكاملة لحسابات الأعضاء مع حالة الوصول الحالية وstate_version. هي آلية الإصلاح: ما فات أي حدث تصلحه اللقطة.
- صفحات بحد أقصى 500 عضو، وبحد أقصى 1000 صفحة، كلها بنفس snapshot_id وgenerated_at. الترتيب لا يهم.
- generated_at وقت بصيغة RFC 3339 مع Z أو فرق التوقيت، لا يتقدم أكثر من 5 دقائق، ولا يزيد عمره عند الإرسال على 72 ساعة.
- عندما تصل كل الصفحات، يُحظر الأعضاء الذين يعرفهم قُرب ولا يظهرون في القائمة؛ لذلك أدرج كل حسابات الأعضاء وليس الفعّالة فقط. ولا يُحظر بالغياب عضو كان أول دخول له قبل generated_at بأقل من 10 دقائق، أو بعده.
- حدث الوصول الأحدث يتقدم على اللقطة لذلك العضو.
مكابح الأمان
الحذف
أرسل member.deleted فقط لطلب حذف معتمد، مع requested_at بوقت تقديم الطلب. يمحو قُرب بيانات العضو الشخصية في المجتمع ويزيل الربط. لا رجعة فيه؛ ولا ترسل بعده شيئاً عن ذلك الـ sub.
باستخدام حزم المطورين
الحزمتان تبنيان هذه الأحداث وتوقعانها وترسلانها، وترفضان محلياً ما سيرفضه قُرب. البناء لا يرسل شيئاً — احفظ الناتج في جدول الصادر؛ والإرسال لا يعيد المحاولة من تلقاء نفسه.
import { GurbPartnerEvents } from '@gurb/server' // ≥ 1.8.0
const events = new GurbPartnerEvents({
communityId: process.env.GURB_COMMUNITY_ID!,
secret: process.env.GURB_EVENTS_SECRET!, // whsec_… — during a rotation: [newest, previous]
baseUrl: 'https://community.example.com',
})
// 1. Build — pure. Store it in YOUR outbox, in the same transaction as the change.
const evt = events.accessChanged({ sub, stateVersion: Date.now(), access: 'blocked' })
await tx.outbox.insert({ id: evt.id, payload: JSON.stringify(evt) })
// 2. Send — from your worker. Never throws for HTTP or network failures.
const result = await events.send(JSON.parse(row.payload))
if (result.outcome === 'delivered') markDelivered(row) // applied, duplicate, stale, unknown member
else if (result.outcome === 'retry') scheduleRetry(row) // 408 / 429 / 5xx / network
else alertHuman(row, result.code) // 400 / 401 / 403 / 404use Gurb\{GurbPartnerEvents, PartnerEvent, PartnerSendResult}; // gurb/sdk ≥ 1.8
$events = new GurbPartnerEvents(
getenv('GURB_COMMUNITY_ID'),
getenv('GURB_EVENTS_SECRET'), // during a rotation: [$newest, $previous]
'https://community.example.com',
);
$event = $events->accessChanged($member->externalId, $member->version, 'blocked');
$outbox->insert($event->id, json_encode($event->toArray()));
$result = $events->send(PartnerEvent::fromArray(json_decode($row->payload, true)));
match ($result->outcome) {
PartnerSendResult::DELIVERED => $outbox->markDelivered($row),
PartnerSendResult::RETRY => $outbox->scheduleRetry($row),
PartnerSendResult::REJECTED => $alerts->raise($row, $result->code),
};| الدالة | متى |
|---|---|
accessChanged | عند كل تغيير في وصول العضو. |
sessionRevoked | أنهت استعادة كلمة المرور أو تغيير البريد دخول العضو لديك. |
memberUpdated | تغيّر حقل مشترك: الاسم أو البريد أو الصورة. |
memberDeleted | طلب حذف معتمد. |
snapshot | كل ليلة. تعيد كل صفحات القائمة الكاملة. |
ping | «اختبار الاتصال». |
الحدود
| الحد | القيمة |
|---|---|
| sub، عدد الأحرف | 255 |
| name، عدد الأحرف | 200 |
| avatar_url، عدد الأحرف | 2048 |
| ملف الصورة | JPEG أو PNG أو WebP · ≤ 2 ميغابايت |
| أعضاء في صفحة اللقطة | 500 |
| صفحات في اللقطة | 1000 |
| فرق الساعة المسموح (webhook-timestamp) | ± 5 دقائق |
| generated_at | ≤ 5 دقائق للأمام · ≤ 72 ساعة عمراً |
| الطلبات | دفعة 500 · 50 في الثانية |
| مدة إعادة المحاولة لديك | 72 ساعة |
تبديل سر الأحداث
- يصدر قُرب سراً جديداً ويُبقي السابق صالحاً.
- توقّع بالسرّين (الأحدث أولاً)، ثم بالجديد وحده.
- يُلغي قُرب السر السابق. لا يُرفض أي حدث في أي لحظة.
