رُوجع 2026-11-11 · إصدار API 2026-11-09 · قراءة Markdown
خطافات الويب للعملاء
تسليم الأحداث الصادرة لمساحة عملك. سجّل نقطة نهاية HTTPS، وتحقق من سر التوقيع لمرة واحدة، واستقبل أحداثًا موقّعة مع إعادة محاولات محدودة.
تسجيل نقطة نهاية
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- يُعاد سر التوقيع (
whsec_…) مرة واحدة: في أول استجابة إنشاء ناجحة. احفظه؛ إعادة التشغيل الاصطناعية (idempotent) للإنشاء نفسه تعيد نقطة النهاية دون السر، ولا يمكن عرضه مرة أخرى. - يجب أن تكون الوجهات HTTPS، وقابلة للحل علنًا، وخالية من بيانات الاعتماد المضمّنة. تُرفض الطلبات إلى العناوين الخاصة وloopback وlink-local (بما في ذلك بيانات وصف السحابة) وunique-local والمتعددة البث قبل إجراء أي اتصال، ولا تُتبع عمليات إعادة التوجيه أبدًا.
- يدرج التسجيل حدث
webhook.verificationموجّهًا لتلك النقطة، بمعزل عن فلترeventTypesالخاص بها. لا تتدفق الأحداث العادية إلا بعد أن تجيب نقطة نهايتك عن التحقق بـ 2xx.
التحقق من عمليات التسليم
كل طلب يحمل:
| الترويسة | المعنى |
|---|---|
x-publisher-event-id | معرّف حدث ثابت: متطابق عبر إعادة المحاولة وإعادة التشغيل |
x-publisher-event-type | نوع الحدث، مثل post.published |
x-publisher-timestamp | ثوانٍ Unix |
x-publisher-signature | t=<ts>,v1=<hex> |
التوقيع هو HMAC-SHA256 على ${t}.${event_id}.${raw_body} باستخدام
سر التوقيع الخاص بك. تحقق بتسامح ±300 ثانية وارفض إعادة التشغيل
خارجه. مثال Node:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
تحقق دائمًا من الجسم الخام للطلب قبل التحليل.
غلاف الحدث
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
كتالوج الأحداث الأولي (قابل للتوسيع؛ يفلتر eventTypes عند التسجيل):
webhook.verification: حمولة تحدٍّ؛ أجب بـ 2xx لتفعيل نقطة النهايةpost.published: وجهة واحدة مؤكدة بإيصال أصليdelivery.failed: وجهة واحدة فشلت نهائيًاdelivery.requires_action: مطلوبة موافقة/إعادة ربط/مراجعة متأخرة
نتائج المنشور الإجمالية (post.partially_published وpost.failed) لا
تُصدر بعد؛ وهي موثقة هنا فقط بمجرد وجود منتج لها، فلا
تعتمد عليها. اشترك في أحداث كل وجهة أعلاه واشتق حالة
الدفعة من نتائج تسليم المنشور.
إعادة المحاولة وإعادة التشغيل والتعطيل
- المحاولات: فورًا، ثم +1m و+5m و+30m و+2h و+8h. تعيد المحاولات استخدام معرّف الحدث نفسه وجسمًا متطابقًا بايت ببايت حتى تتمكن من إزالة التكرار بأمان.
- 2xx = تم التسليم. يعاد 429/5xx/انتهاء المهلة. تفشل 4xx الأخرى نهائيًا لذلك الحدث (أصلح نقطة النهاية ثم أعد التشغيل).
- 410 Gone تعطّل نقطة النهاية: لا تُدرج لها أحداث أخرى.
- إعادة التشغيل المصرَّح بها من المشغّل عبر خدمة خطافات الويب الداخلية تعيد إرسال حدث بمعرّفه الأصلي. لا تُسحب أبدًا محاولة جارية مستأجَرة نشطة؛ تُبلِّغ إعادة التشغيل أن الحدث مشغول ويمكن إعادة محاولته قريبًا.
ملاحظات تشغيلية
- تخزن تشخيصات التسليم رموز نتائج آمنة فقط: أبدًا سرك أو التوقيعات أو ترويسات الطلبات أو أجسام الاستجابات. تُنظَّف الحمولات أيضًا: تُزال أسرار المزود/OAuth وعناوين URL للوسائط المسبقة التوقيع قبل إدراج أي شيء.
- نقاط النهاية محددة بنطاق مساحة العمل: امتلاك معرّف UUID لنقطة نهاية من مساحة عمل أخرى لا يجدي شيئًا.
- التسليم مرة واحدة على الأقل لكل وقوع حدث مقبول؛ أزل التكرار على
x-publisher-event-id.
توفر أدوات المطوّر
تعرض صفحة Developers مفاتيح API لمساحة العمل ونقاط نهاية خطافات الويب بشكل مستقل عن تكوين تشفير سر التوقيع. يتطلب إنشاء خطاف ويب تكوين تشفير خادم صالحًا؛ اطلب من مشغّل النشر حلّ تحذير التكوين. تبقى إدارة مفاتيح API متاحة. أسرار التوقيع الموجودة لا تُعرض أبدًا مرة أخرى.