ویب ہُکس

کسی انوائرنمنٹ میں جو ہوتا ہے، Usher اسی وقت آپ کے سرورز کو بتا سکتا ہے: کوئی شامل ہوا، سائن ان کیا، اپنی تفصیلات بدلیں یا چلا گیا۔ ہر ایونٹ آپ کے چنے ہوئے پتے پر ایک سائن شدہ POST ہے، اور اگر آپ کا سرور جواب نہ دے تو دوبارہ کوشش کی جاتی ہے۔

اینڈ پوائنٹ شامل کریں

Usher Console میں انوائرنمنٹ کھولیں، پھر ویب ہُکس ← نیا اینڈ پوائنٹ۔ اپنا ایک https:// پتہ دیں اور چنیں کہ اسے کن ایونٹس کی خبر ملنی چاہیے۔ Console اینڈ پوائنٹ کا سائننگ سیکرٹ (whsec_…) ایک بار دکھاتا ہے: اسے اپنے سرور کے باقی سیکرٹس کے ساتھ رکھیں۔

ٹیسٹ بھیجیں صرف اسی اینڈ پوائنٹ کو ایک webhook.test ایونٹ بھیجتا ہے، چاہے اس نے کسی بھی ایونٹ کو سبسکرائب کیا ہو۔

کیا پہنچتا ہے

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

ایونٹس لوگوں اور سیشنز کو بیان کرتے ہیں، کبھی سیکرٹس کو نہیں: نہ ٹوکنز، نہ پاس ورڈ ہیش، نہ کردار، اور نہ یہ کہ کسی پر پابندی کیوں لگی۔

ہر ڈیلیوری جانچیں

Usher Standard Webhooks کی تفصیلات کے مطابق سائن کرتا ہے، اس لیے اس کی کوئی بھی لائبریری آپ کے لیے دستخط جانچ لیتی ہے۔ جو تصدیق نہ پائے اسے مسترد کریں۔ لائبریریاں پانچ منٹ سے زیادہ فرق والے ٹائم اسٹیمپ کو بھی مسترد کرتی ہیں، اس لیے پرانی ڈیلیوری دوبارہ نہیں چلائی جا سکتی۔

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• 15 سیکنڈ کے اندر جواب دیں، کسی بھی 2xx کے ساتھ۔ اس کے علاوہ کچھ بھی، بشمول ری ڈائریکٹ، ناکامی شمار ہوتا ہے۔
• دہرائے جانے کی توقع رکھیں۔ ہر کوشش میں پیغام کا webhook-id وہی رہتا ہے؛ جو آپ سنبھال چکے ہوں اسے چھوڑ دیں۔
• ترتیب پر انحصار نہ کریں۔ دوبارہ بھیجے گئے پیغامات نئے ایونٹس کے بعد پہنچ سکتے ہیں۔

جب آپ کا سرور جواب نہ دے

Usher بالترتیب 5 سیکنڈ، 5 منٹ، 30 منٹ، 2 گھنٹے، 5 گھنٹے، 10 گھنٹے اور 10 گھنٹے بعد دوبارہ کوشش کرتا ہے (کل ملا کر تقریباً ڈیڑھ دن)، پھر چھوڑ دیتا ہے۔ Console کا ڈیلیوری لاگ ہر پیغام کی کوششیں اور آپ کے سرور کا آخری جواب دکھاتا ہے، اور دوبارہ بھیجیں ڈیلیوری کو نئے سرے سے شروع کرتا ہے۔

نیا سیکرٹ

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

ڈیلیوریز کہاں سے آتی ہیں

ویب ہُکس Usher سے اس کی ایگریس پراکسی کے ذریعے نکلتے ہیں، جو نجی یا اندرونی پتوں سے نہیں جڑتی۔ اینڈ پوائنٹ کا کسی عوامی نام پر https:// پتہ ہونا لازمی ہے: IP پتہ، نجی نام، یا Usher کے اپنے ڈومینز کا پتہ نہیں۔