eWوثائق eWasl

Webhooks

اشترك في أحداث دورة حياة المنشور عبر Webhooks بـ HTTPS مع حمولات موقّعة بـ HMAC.

تتيح Webhooks لتطبيقك استقبال إشعارات فورية عندما ينتقل منشور عبر مسار النشر — دون استطلاع GET /api/v1/posts.

النقاط الطرفية

الطريقةالمسارالأداة / النطاق
GET/api/v1/webhookslist_webhooks · posts:read
POST/api/v1/webhooksregister_webhook · posts:create
DELETE/api/v1/webhooks/{id}delete_webhook · posts:create

تتطلب كل النقاط Authorization: Bearer ewasl_... وخطة Pro فأعلى.

الأحداث

الحدثيُطلق عندما
post.publishedنجحت كل المنصّات.
post.partially_publishedنجحت منصة واحدة على الأقل وفشلت واحدة على الأقل.
post.failedفشلت كل المنصّات.
post.scheduledأُدرج منشور مجدول جديد.

التسجيل

curl -X POST https://app.ewasl.com/api/v1/webhooks \
  -H "Authorization: Bearer ewasl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/ewasl",
    "events": ["post.published", "post.failed"],
    "description": "Production webhook"
  }'

يجب أن يكون الرابط HTTPS (تُرفض نقاط HTTP). يمكنك الاشتراك في عدّة أحداث لكل نقطة، أو تسجيل عدّة نقاط.

شكل الحمولة

يحمل كل POST لحدث جسماً JSON:

{
  "id": "evt_01H...",
  "type": "post.published",
  "createdAt": "2026-04-22T23:58:01.123Z",
  "data": {
    "post": {
      "id": "p_01H...",
      "status": "PUBLISHED",
      "publishedAt": "2026-04-22T23:58:00.987Z",
      "results": [
        {
          "platform": "TWITTER",
          "success": true,
          "externalPostId": "1842...",
          "externalUrl": "https://x.com/eWasl/status/1842..."
        }
      ]
    }
  }
}

في post.partially_published و post.failed، تحتوي مصفوفة results على عنصر لكل منصة جرى محاولتها مع success: false و error معبّأ.

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

يتضمّن كل طلب ترويسة توقيع HMAC:

X-eWasl-Signature: t=1714000000,v1=5e8a...

تحقّق منها قبل الوثوق بالحمولة. (يُولَّد السرّ المشترك عند تسجيل الـ webhook ويُعرض مرة واحدة في الاستجابة.)

import crypto from 'node:crypto';
 
function verify(rawBody: string, signatureHeader: string, secret: string) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('=') as [string, string]),
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

ارفض الطلبات التي يكون فيها Math.abs(now - parts.t) > 300 ثانية لمنع هجمات إعادة التشغيل.

إعادة المحاولات

إن أعادت نقطتك استجابة غير 2xx، يعيد eWasl المحاولة بتراجع أُسّي: دقيقة، 5 دقائق، 30 دقيقة، ساعتين، 12 ساعة. بعد الإخفاق الخامس، يُعطَّل الـ webhook تلقائياً ويُكشَف failure_count عبر GET /api/v1/webhooks لتتمكّن من إعادة تفعيله بعد إصلاح المستقبِل.

التطوير المحلي

استخدم smee.io أو ngrok لتمرير حركة webhooks بـ HTTPS إلى خادم محلي أثناء التطوير.

في هذه الصفحة