वेबहुक का परिचय

Sursa हर अहम बदलाव के लिए एक इवेंट दर्ज करता है: कार्ड प्रकाशित, सत्यापित या आर्काइव होता है, कोई घोषणा पढ़ी जाती है, किसी सवाल का जवाब नहीं मिलता। इवेंट आप दो तरीक़ों से पा सकते हैं, और दोनों को साथ में भी इस्तेमाल कर सकते हैं:

	वेबहुक	इवेंट फ़ीड
कैसे	Sursa हर इवेंट होते ही आपके HTTPS पते पर भेजता है।	आप जब चाहें, `GET /v1/webhook-events` पढ़ते हैं।
देरी	कुछ सेकंड।	जितनी बार आप पोलिंग करते हैं।
क्या चाहिए	एक पब्लिक HTTPS प्राप्तकर्ता।	सिर्फ़ `admin` रोल और `webhooks:manage` स्कोप वाली API कुंजी।
किसके लिए अच्छा	बदलावों पर प्रतिक्रिया: सूचना देना, सिंक करना, वर्कफ़्लो शुरू करना।	बैच जॉब, रुकावट के बाद छूटा हुआ पकड़ना, मिलान।

दोनों में वही इवेंट, वही ID के साथ आते हैं। हर इवेंट फ़ीड में 30 दिन तक रहता है, चाहे किसी वेबहुक ने उसे सब्सक्राइब किया हो या नहीं।

इवेंट

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

फ़ील्ड	मतलब
`id`	इवेंट की ID, `evt_` और 32 हेक्साडेसिमल अक्षर। डिलीवरी के हर प्रयास में और फ़ीड में एक ही।
`type`	क्या हुआ, `<object>.<past-tense verb>` रूप में: `card.updated`, `access_request.resolved`।
`created_at`	बदलाव कब हुआ, UTC में।
`api_version`	API का वह वर्शन, जिसके स्कीमा का `data` पालन करता है।
`object`	उस ऑब्जेक्ट का टाइप और ID, जिसके बारे में इवेंट है।
`data`	विवरण। इसका ढाँचा टाइप पर निर्भर करता है और इवेंट कैटलॉग में बताया गया है।
`data.previous_attributes`	`*.updated` इवेंट में: बदले गए फ़ील्ड के पिछले मान।
`sequence`, `payload`, `test`	सिर्फ़ वेबहुक की डिलीवरी में: वेबहुक के क्रम में स्थिति, पेलोड मोड, और क्या यह टेस्ट इवेंट है।

data में सिर्फ़ वही होता है, जो ऑब्जेक्ट का कोई भी पाठक API से देख सकता है। इसमें कभी ऐक्सेस सूचियाँ, दूसरे लोगों की अनुमतियाँ या छिपे फ़ील्ड नहीं होते। इवेंट में कारण छोटे न्यूट्रल कोड होते हैं, जैसे no_hits, restricted या index_failed।

इवेंट टाइप

इवेंट इन क्षेत्रों को कवर करते हैं:

क्षेत्र	उदाहरण
कार्ड	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
सत्यापन	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
संरचना	`collection.created`, `folder.updated`
सहयोग	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
जवाब	`question.unanswered`, `question.feedback_created`, `access_request.created`
लोग और ऐक्सेस	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
स्रोत और इम्पोर्ट	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
जॉब	`job.completed`, `job.failed`, `export.ready`
वेबहुक	`webhook.endpoint_disabled`, `webhook.ping`

स्कीमा और हर इवेंट के उदाहरण के साथ पूरी सूची API रेफ़रेंस के इवेंट कैटलॉग में है। GET /v1/webhooks/catalog आपके इंस्टॉलेशन पर उपलब्ध टाइप लौटाता है।

समय के साथ नए इवेंट टाइप जुड़ते हैं, और मौजूदा इवेंट में फ़ील्ड जुड़ते हैं। इवेंट टाइप का नाम कभी नहीं बदलता और उन्हें कभी हटाया नहीं जाता। आपके प्राप्तकर्ता को वे टाइप और फ़ील्ड छोड़ देने चाहिए, जिन्हें वह नहीं जानता।

कौन क्या पाता है

वेबहुक को इवेंट सिर्फ़ तब मिलता है, जब इवेंट का ऑब्जेक्ट वेबहुक को दिखता है, उसी तरह जैसे API कुंजी को: उसके रोल, उसकी डेटा प्रोफ़ाइल और उसके कलेक्शन के आधार पर। support कलेक्शन तक सीमित वेबहुक को finance के कार्ड के बारे में इवेंट कभी नहीं मिलते। लोगों, कुंजियों, स्रोतों, इम्पोर्ट, जॉब, एक्सपोर्ट, बिलिंग, ऐप और ख़ुद वेबहुक के बारे में इवेंट सिर्फ़ admin रोल वाले वेबहुक को जाते हैं।

इसके अंदर हर वेबहुक अपने इवेंट चुनता है:

टाइप से, मास्क के साथ: हर कार्ड इवेंट के लिए card.*, हर इवेंट के लिए *;
कार्ड इवेंट के लिए कलेक्शन और टैग से।

वेबहुक का पेलोड मोड full (data के साथ इवेंट, डिफ़ॉल्ट) या thin (data के बिना इवेंट: आपका प्राप्तकर्ता अपनी कुंजी से API के ज़रिए ऑब्जेक्ट पढ़ता है, और हमेशा उसकी मौजूदा स्थिति देखता है) होता है।

डिलीवरी संक्षेप में

JSON के रूप में इवेंट के साथ HTTPS POST, वेबहुक के सीक्रेट से दो फ़ॉर्मेट में साइन किया हुआ: Standard Webhooks (webhook-signature) और पुराना X-KB-Signature।
10 सेकंड के अंदर कोई भी 2xx जवाब सफलता है।
असफल डिलीवरी का लगभग तीन दिन तक बढ़ते अंतराल पर रीट्राई होता है। 429 या 503 जवाब में Retry-After का पालन होता है; 410 वेबहुक को बंद कर देता है; लगातार 10 असफलताएँ उसे तब तक पॉज़ कर देती हैं, जब तक उसे फिर से शुरू न किया जाए।
एक वेबहुक की डिलीवरी सख़्ती से क्रम में भेजी जाती हैं। धीमा वेबहुक दूसरे वेबहुक को देर नहीं कराता।
एक ही इवेंट एक से ज़्यादा बार आ सकता है: डुप्लिकेट को webhook-id से हटाएँ।

वेबहुक पाना में पूरा प्राप्तकर्ता दिखाया गया है, Node.js, Python और Go में सिग्नेचर की जाँच के साथ।

वेबहुक मैनेज करें

काम	एंडपॉइंट
वेबहुक बनाएँ और उसका सीक्रेट पाएँ	`POST /v1/webhooks`
पता, इवेंट या स्थिति बदलें	`PATCH /v1/webhooks/{webhook_id}`
टेस्ट इवेंट भेजें	`POST /v1/webhooks/{webhook_id}/test`
सीक्रेट रोटेट करें	`POST /v1/webhooks/{webhook_id}/rotate-secret`
पॉज़ किया गया वेबहुक फिर से शुरू करें	`POST /v1/webhooks/{webhook_id}/resume`
डिलीवरी और जवाब देखें	`GET /v1/webhooks/{webhook_id}/deliveries`
डिलीवरी फिर से भेजें	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

वेबहुक मैनेज करने के लिए admin रोल और webhooks:manage स्कोप वाली कुंजी चाहिए, या एडमिन इंटरफ़ेस में एडमिन। एक संगठन में 20 तक वेबहुक हो सकते हैं। वेबहुक संगठन के प्लान का हिस्सा हैं; उनके बिना ये एंडपॉइंट कोड webhooks.feature_disabled के साथ 403 से जवाब देते हैं।