वेबहुक

एखाद्या एन्व्हायर्नमेंटमध्ये जे घडते ते घडताक्षणी 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 च्या स्वतःच्या डोमेनवरील पत्ता नव्हे.