Webhooks

Webhook آپ کے سرور پر ایک پتہ ہے جسے Posty5 کچھ ہونے پر کال کرتا ہے۔ Posty5 سے نئے وزٹس پوچھنے کے بجائے، آپ کے سسٹم کو چند سیکنڈز میں ایک JSON ایونٹ کے ساتھ بتایا جاتا ہے جس کی وہ تصدیق کر سکتا ہے۔

Note

Webhooks آپ کے پلان پر منحصر ہیں۔ ڈیلیوری پر کوئی کریڈٹ خرچ نہیں ہوتا۔ تفصیلات کے لیے کریڈٹس کا صفحہ دیکھیں۔ فیچر کریڈٹس

ایک اینڈ پوائنٹ بنائیں

1. Posty5 ڈیش بورڈ میں اکاؤنٹ کی ترتیبات کھولیں اور Webhooks منتخب کریں۔

2. ایک اینڈ پوائنٹ شامل کریں، اس کا HTTPS پتہ درج کریں اور وہ ایونٹس منتخب کریں جو اسے ملیں گے۔

3. اپنے تمام لنکس اور QR کوڈز یا صرف کچھ منتخب کریں، بوٹ وزٹس گنے جائیں یا نہیں، اور ایونٹس ایک ایک کر کے آئیں یا بیچ میں۔

4. محفوظ کریں، پھر سائننگ سیکرٹ کاپی کریں۔ یہ صرف اسی ایک بار دکھایا جاتا ہے۔

5. ٹیسٹ بھیجیں استعمال کر کے چیک کریں کہ آپ کا سرور 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	صرف تب بھیجا جاتا ہے جب آپ ٹیسٹ بھیجیں استعمال کرتے ہیں۔

وزٹ اور اسکین ایونٹس ابھی نہیں بھیجے جاتے

فی الحال Posty5 صرف ٹیسٹ ایونٹ بھیجتا ہے۔ وزٹ اور اسکین ایونٹس، اور ان کے مائل اسٹونز، وزٹس کے تجزیات جاری ہونے پر شروع ہوں گے۔ آپ ابھی اینڈ پوائنٹس بنا اور ٹیسٹ کر سکتے ہیں، اور تب وہ کسی تبدیلی کے بغیر وہ ایونٹس وصول کرنا شروع کر دیں گے۔

اسٹیٹک QR کوڈز کوئی ایونٹ نہیں بھیجتے

اسٹیٹک QR کوڈ اپنا مواد براہ راست رکھتا ہے، اس لیے اسکین کبھی Posty5 تک نہیں پہنچتا اور کوئی ایونٹ نہیں بھیجا جا سکتا۔ صرف ڈائنامک QR کوڈز اور شارٹ لنکس ایونٹس بناتے ہیں۔

ایونٹ کیسا دکھتا ہے

ہر ایونٹ ایک JSON POST ہے جس میں ایک id، ایک type، 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 ہوتا ہے جس میں میٹرک، پہنچی ہوئی قدر اور کب پہنچی شامل ہیں، اور کوئی وزٹ نہیں۔

بیچ ڈیلیوری میں، batch قسم کا ایک POST data.events میں زیادہ سے زیادہ 500 ایونٹس لے جاتا ہے۔

کیا کبھی نہیں بھیجا جاتا

ایونٹس میں کبھی وزیٹر کا IP پتہ، مکمل یوزر ایجنٹ، مکمل ریفرر پتہ، وزیٹر شناخت کنندہ یا آپ کی اکاؤنٹ ID نہیں ہوتی۔ بوٹ وزٹس خارج رہتے ہیں جب تک آپ انہیں شامل نہ کریں۔

دستخط کی تصدیق کریں

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 ایونٹس کی تصدیق کرتی ہے۔

Caution

باڈی کی تصدیق بالکل ویسے ہی کریں جیسے وہ موصول ہوئی۔ JSON کو پارس کر کے دوبارہ سیریلائز کرنے سے بائٹس بدل جاتے ہیں اور دستخط ٹوٹ جاتا ہے۔

دوبارہ کوششیں اور ناکامیاں

• 10 سیکنڈز کے اندر کسی بھی 2xx اسٹیٹس کے ساتھ جواب دیں۔ باقی سب ناکامی شمار ہوتا ہے۔
• ناکام ڈیلیوری 30 سیکنڈ، 2 منٹ، 10 منٹ، 1 گھنٹہ، 6 گھنٹے اور 24 گھنٹے بعد دوبارہ کی جاتی ہے، پھر چھوڑ دی جاتی ہے۔
• ہر دوبارہ کوشش میں وہی webhook-id ہوتی ہے، تاکہ آپ کا سرور پہلے سے سنبھالا گیا ایونٹ نظرانداز کر سکے۔
• کم از کم 24 گھنٹوں میں مسلسل 20 ناکام ڈیلیوریز کے بعد، یا 410 Gone جواب دینے پر فوراً، اینڈ پوائنٹ بند کر دیا جاتا ہے۔ آپ کو ایک اطلاع ملتی ہے، اور آپ اسے ڈیش بورڈ سے دوبارہ آن کر سکتے ہیں۔
• اینڈ پوائنٹ کی ڈیلیوری فہرست ہر کوشش کو اس کے اسٹیٹس اور آپ کے سرور کے جواب کے ساتھ دکھاتی ہے، اور آپ کو ڈیلیوری دوبارہ بھیجنے دیتی ہے۔

سیکرٹ تبدیل کریں

اگر سیکرٹ لیک ہو گیا ہو، تو اسے اینڈ پوائنٹ کے مینو سے تبدیل کریں۔ 24 گھنٹوں تک ڈیلیوریز میں دو دستخط ہوتے ہیں، ہر سیکرٹ کا ایک، تاکہ آپ ایونٹس کھوئے بغیر اپنا سرور اپ ڈیٹ کر سکیں۔

بغیر کوڈ کے، n8n میں

Posty5 Trigger نوڈ آپ کے لیے اینڈ پوائنٹ بناتا اور اس کی تصدیق کرتا ہے۔ n8n Posty5 Trigger