Webhooks

الـ Webhook عنوان على خادمك يستدعيه Posty5 عند حدوث شيء ما. فبدلًا من أن يسأل نظامك Posty5 عن الزيارات الجديدة، يُبلَّغ خلال ثوانٍ بحدث JSON يمكنه التحقق منه.

إنشاء نقطة استقبال

في لوحة تحكم Posty5، افتح إعدادات الحساب واختر Webhooks.
أضف نقطة استقبال، وأدخل عنوان HTTPS الخاص بها، واختر الأحداث التي تستقبلها.
اختر كل روابطك ورموز QR أو بعضها فقط، وهل تُحتسب زيارات البرامج الآلية، وهل تصل الأحداث واحدًا تلو الآخر أو على دفعات.
احفظ، ثم انسخ مفتاح التوقيع السري. يظهر مرة واحدة فقط.
استخدم إرسال تجربة للتأكد من أن خادمك يستقبل حدث webhook.test ويتحقق منه.

يجب أن يستخدم العنوان HTTPS وأن يكون متاحًا من الإنترنت. تُرفض عناوين الشبكات الخاصة والمحلية، ولا تُتبع عمليات إعادة التوجيه. يمكنك امتلاك حتى 10 نقاط استقبال.

الأحداث

Event
`short_link.visited`	فتح شخص أحد روابطك المختصرة، بما في ذلك عبر صورة QR الخاصة بالرابط.
`short_link.visits_milestone`	وصل رابط مختصر إلى أحد أعداد الزيارات التي حددتها (حتى 10 قيم).
`qr_code.scanned`	مسح شخص أحد رموز QR الديناميكية الخاصة بك.
`qr_code.scans_milestone`	وصل رمز QR إلى أحد أعداد المسح التي حددتها.
`webhook.test`	يُرسل فقط عند استخدام إرسال تجربة.

شكل الحدث

كل حدث طلب POST بصيغة JSON يحتوي على معرّف ونوع وإصدار API ووقت الإنشاء وبياناته، أي الرابط أو رمز QR والزيارة.

{
  "id": "evt_6700f1c2a9e4b51d2c3f0a11",
  "type": "short_link.visited",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "target": {
      "type": "shortLink",
      "id": "66f0c2a9e4b51d2c3f0a1122",
      "code": "aB3xY9",
      "url": "https://pst5.com/_aB3xY9",
      "name": "Spring sale",
      "destinationUrl": "https://shop.example/sale",
      "tag": "spring",
      "refId": null
    },
    "visit": {
      "at": "2026-10-04T11:59:59.120Z",
      "channel": "qr",
      "country": "EG",
      "deviceType": "mobile",
      "os": "Android",
      "browser": "Chrome",
      "referrerHost": null,
      "language": "ar",
      "isBot": false,
      "outcome": "redirect"
    }
  }
}

تحمل أحداث الإنجاز الحقل data.milestone مع المقياس والقيمة التي وُصل إليها ووقتها، دون بيانات زيارة.

عند التسليم على دفعات، يحمل طلب POST واحد من النوع batch حتى 500 حدث في data.events.

ما لا يُرسل أبدًا

لا تحتوي الأحداث أبدًا على عنوان IP للزائر، ولا معرّف المتصفح الكامل، ولا عنوان الإحالة الكامل، ولا معرّف الزائر، ولا معرّف حسابك. وتُستبعد زيارات البرامج الآلية ما لم تضمّنها.

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

يوقّع Posty5 كل عملية تسليم بالمفتاح السري لنقطة الاستقبال، وفق مواصفة Standard Webhooks، في ثلاث ترويسات. ارفض أي طلب لا يطابق توقيعه أو يزيد عمر طابعه الزمني على 5 دقائق.

webhook-id
webhook-timestamp
webhook-signature

في Node.js، استخدم حزمة ‎@posty5/webhooks.

import { verifyWebhookSignature } from "@posty5/webhooks";

// rawBody is the request body exactly as received, before JSON parsing.
const event = verifyWebhookSignature({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.POSTY5_WEBHOOK_SECRET,
});

في ‎.NET، استخدم حزمة Posty5.Webhooks.

using Posty5.Webhooks;

var webhookEvent = WebhookSignature.Verify(rawBody, headers, secret);

في أي لغة أخرى، تتحقق أي مكتبة لـ Standard Webhooks من أحداث Posty5 باستخدام مفتاحك السري.

إعادة المحاولة والإخفاق

أجب بأي حالة 2xx خلال 10 ثوانٍ. وأي رد آخر يُعد إخفاقًا.
تُعاد محاولة التسليم الفاشل بعد 30 ثانية ودقيقتين و10 دقائق وساعة و6 ساعات و24 ساعة، ثم يتوقف.
تحمل كل إعادة محاولة قيمة webhook-id نفسها، ليتمكن خادمك من تجاهل حدث عالجه من قبل.
تُعطَّل نقطة الاستقبال بعد 20 تسليمًا فاشلًا متتاليًا على مدى 24 ساعة على الأقل، أو فورًا إذا أجابت بالحالة 410 Gone. يصلك إشعار، ويمكنك إعادة تفعيلها من لوحة التحكم.
تعرض قائمة عمليات التسليم لنقطة الاستقبال كل محاولة بحالتها ورد خادمك، وتتيح لك إعادة إرسال أي تسليم.

تغيير المفتاح السري

إذا احتمل تسرّب المفتاح السري، غيّره من قائمة نقطة الاستقبال. ولمدة 24 ساعة تحمل عمليات التسليم توقيعين، واحدًا لكل مفتاح، لتحدّث خادمك دون أن تفوتك أحداث.

دون برمجة، في n8n

تُنشئ عقدة Posty5 Trigger نقطة الاستقبال وتتحقق منها نيابةً عنك. مشغّل Posty5 في n8n