KYB webhook: इवेंट, payload और साइनिंग

Didit के KYB webhooks आपके backend को बताते हैं कि कोई व्यवसाय सत्यापन सत्र कब अपनी स्थिति बदलता है, या कब कोई समीक्षक या रजिस्ट्री अपना डेटा बदलती है। व्यावसायिक इकाइयों के अपने अलग इवेंट होते हैं। उन events की सदस्यता webhook गंतव्य API या Business Console के ज़रिए लें।

इवेंट सूची

सत्र इवेंट उपयोगकर्ता और व्यवसाय सत्रों में साझा होते हैं। Payload पर मौजूद session_kind field बताता है कि event किस प्रकार के session से जुड़ा है। इकाई-स्तर के events, session-level events से अलग होते हैं।

सत्र-स्तर के events

Event	कब सक्रिय होता है
`status.updated`	सत्र की स्थिति बदलती है। व्यवसाय सत्यापन (KYB) सत्र के लिए payload में `session_kind: "business"` होता है। प्रगति जानने के लिए यही event देखें।
`data.updated`	समीक्षक ने console में रजिस्ट्री डेटा संपादित किया, प्रमुख व्यक्ति (Key People) को छोड़ा या दोबारा बनाया, या रजिस्ट्री ने कोई बदलाव रिपोर्ट किया (रजिस्ट्री निगरानी उपलब्ध होने पर)। कौन-सा कारण है, यह `trigger` field बताता है।

जब आवेदक दस्तावेज़ अपलोड करता है, प्रमुख व्यक्ति सबमिट करता है, या AML rescan पूरा होता है, तब data.updated नहीं भेजा जाता। उस प्रगति को देखने के लिए status.updated का उपयोग करें, या session का निर्णय प्राप्त करें।

व्यवसाय इकाई इवेंट

Event	कब सक्रिय होता है
`business.status.updated`	जुड़ी हुई व्यवसाय इकाई की स्थिति बदलती है (`ACTIVE` / `FLAGGED` / `BLOCKED`)।
`business.data.updated`	Business entity के प्रोफ़ाइल फ़ील्ड या समेकित काउंटर बदलते हैं।

अपने webhook गंतव्य पर इनमें से कोई भी संयोजन सब्सक्राइब किया जा सकता है। Business और User entity events का पूरा संदर्भ देखने के लिए इकाई webhook पढ़ें।

Payload संरचना

Session webhooks में बिना data wrapper वाला flat payload होता है। Envelope, signature headers और सभी साझा फ़ील्ड webhooks reference में दर्ज हैं। KYB session के payload में ये फ़ील्ड और जुड़ते हैं:

फ़ील्ड	प्रकार	विवरण
`session_kind`	`"business"`	इससे सामान्य हैंडलर KYC और KYB के बीच अंतर कर सकता है।
`business_session_id`	`uuid`	`session_id` के बराबर।
`vendor_business_id`	string	सत्र बनाते समय दिया गया, व्यवसाय इकाई का आपका पहचानकर्ता (जब दिया गया हो)।
`status`	string	सटीक लेबल, जैसे `"In Progress"`, `"Approved"` या `"Awaiting User"`। देखें statuses।
`trigger`	string	वैकल्पिक। webhook क्यों भेजा गया। KYB के `data.updated` पर: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` या `"kyb_registry_change"`।
`decision`	object	तब मौजूद होता है जब `status` `Approved`, `Declined`, `In Review` या `Abandoned` हो। इसकी संरचना `GET /v3/session/{id}/decision/` जैसी ही है, देखें रिस्पॉन्स स्कीमा।
`resubmit_info`	object	तब मौजूद होता है जब `status` `Resubmitted` हो।

KYB session के लिए `status.updated`

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

decision block में registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] और अन्य KYB ऐरे होते हैं।

KYB session के लिए `data.updated`

data.updated में वही flat envelope होता है जो status.updated में है, साथ में एक trigger होता है जो बताता है कि event क्यों भेजा गया। जब session की स्थिति Approved, Declined, In Review या Abandoned हो, तब इसमें मौजूदा decision भी होता है। क्या बदला, यह देखने के लिए निर्णय दोबारा प्राप्त करें। Payload में changed_fields सूची नहीं होती।

`business.status.updated` और `business.data.updated`

Entity events भी flat होते हैं। इनमें vendor_business_id, vendor_data, status (ACTIVE, FLAGGED या BLOCKED) और created_at होते हैं। business.status.updated में previous_status जुड़ता है। business.data.updated में changed_fields और { field: { previous, current } } के रूप में changes map जुड़ते हैं।

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

हस्ताक्षर सत्यापन

हर webhook आपके webhook गंतव्य के साझा सीक्रेट का उपयोग करके HMAC-SHA256 से हस्ताक्षरित होता है। Raw request body को X-Signature-V2 header (अनुशंसित) से सत्यापित करें, और वे डिलीवरी अस्वीकार करें जिनका X-Timestamp 300 सेकंड से ज़्यादा पुराना है। सभी हस्ताक्षर हेडर, साइनिंग सीक्रेट रोटेशन की ओवरलैप अवधि और कोड नमूने webhooks reference में दिए गए हैं।

पुनः प्रयास नीति

5xx या 404 रिस्पॉन्स, समय-सीमा समाप्ति या कनेक्शन विफलता पर अधिकतम 2 बार पुनः प्रयास किया जाता है, पहला लगभग 1 मिनट बाद और दूसरा लगभग 4 मिनट बाद, और उसके बाद डिलीवरी छोड़ दी जाती है।
अन्य 4xx और 3xx रिस्पॉन्स पर पुनः प्रयास नहीं किया जाता।
हर पुनः प्रयास में वही event_id रहता है, इसलिए उसी के आधार पर डुप्लिकेट हटाएँ।
webhook गंतव्य के डिलीवरी लॉग से कोई डिलीवरी दोबारा भेजी जा सकती है। पूरी नीति webhooks reference में है।

सदस्यता लेना

webhook गंतव्य पर वे events सब्सक्राइब करें जिनकी आपको परवाह है:

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

अपनी तरफ़ से व्यवसाय सत्र फ़िल्टर करने के लिए status.updated और data.updated events के भीतर session_kind === "business" जाँचें।

अगले चरण

Webhooks संदर्भ

गंतव्य, हस्ताक्षर, पुनः प्रयास और सामान्य पैटर्न।

स्थितियाँ

सत्र और सुविधा की स्थितियों का संदर्भ।

रिस्पॉन्स स्कीमा

KYB निर्णय payload को समझना।

शुरुआत करें

सुविधाएँ

व्यवसाय प्रोफ़ाइल

संदर्भ

कंसोल

KYB webhook: इवेंट, payload और साइनिंग

इवेंट सूची

सत्र-स्तर के events

व्यवसाय इकाई इवेंट

Payload संरचना

KYB session के लिए `status.updated`

KYB session के लिए `data.updated`

`business.status.updated` और `business.data.updated`

हस्ताक्षर सत्यापन

पुनः प्रयास नीति

सदस्यता लेना

अगले चरण

Webhooks संदर्भ

स्थितियाँ

रिस्पॉन्स स्कीमा

​इवेंट सूची

​सत्र-स्तर के events

​व्यवसाय इकाई इवेंट

​Payload संरचना

​KYB session के लिए status.updated

​KYB session के लिए data.updated

​business.status.updated और business.data.updated

​हस्ताक्षर सत्यापन

​पुनः प्रयास नीति

​सदस्यता लेना

​अगले चरण

Webhooks संदर्भ

स्थितियाँ

रिस्पॉन्स स्कीमा

इवेंट सूची

सत्र-स्तर के events

व्यवसाय इकाई इवेंट

Payload संरचना

KYB session के लिए `status.updated`

KYB session के लिए `data.updated`

`business.status.updated` और `business.data.updated`

हस्ताक्षर सत्यापन

पुनः प्रयास नीति

सदस्यता लेना

अगले चरण