सत्यापन इवेंट

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

जो सत्यापन कन्वर्ट नहीं होता, वह कभी verify.verification.verified नहीं भेजता, और केवल उसकी स्थिति से आपको इसका कारण पता नहीं चलता। failed साझा स्थिति है: सत्यापन वहाँ तब पहुँचता है जब बहुत अधिक गलत सत्यापन कोड जमा किए गए हों, तब reason attempts_exhausted के साथ, और तब भी जब डिलीवरी योजना ऐसी विफलताओं के साथ समाप्त हो जो बताती हैं कि कोई सत्यापन कोड नहीं भेजा गया, तब reason undeliverable के साथ। केवल दूसरी स्थिति verify.verification.failed भेजती है, और उस इवेंट में हमेशा reason undeliverable होता है, इसलिए जहाँ स्थिति दोनों को अलग नहीं कर पाती, वहाँ इवेंट करता है। वैधता अवधि बीत जाने पर सत्यापन expired पर पहुँचता है। न expired और न ही प्रयास समाप्त होने वाला failed अपना कोई इवेंट भेजता है। फ़ॉलबैक चैनल अपना verify.attempt.sent बनाता है, इसलिए एक सत्यापन में कई प्रयास अनुक्रम हो सकते हैं।

इवेंट प्रकारों की सूची खुली है: समय के साथ नए प्रकार जोड़े जा सकते हैं, इसलिए किसी अपरिचित मान को त्रुटि नहीं, बल्कि भविष्य का इवेंट मानें।

इवेंट का ढाँचा

इवेंट आपके webhook एंडपॉइंट पर Webhooks गाइड में बताए गए Standard Webhooks नेस्टेड ढाँचे में आते हैं: एक type, एक timestamp, और प्रकार के अनुसार एक data ऑब्जेक्ट। इवेंट की पहचान बॉडी में नहीं होती: वह webhook-id HTTP हेडर में आती है, जो एक ही डिलीवरी के हर फिर से प्रयास में समान रहती है और आपकी डुप्लिकेट हटाने की कुंजी है।

हर इवेंट के data में यह पहचान आधार होता है:

• verification_id: वह सत्यापन जिससे यह इवेंट संबंधित है, जो POST /v1/verify/verifications से मिले id से मेल खाता है
• workspace_id: वह वर्कस्पेस जिसने सत्यापन बनाया
• to: सत्यापन के प्राप्तकर्ता की पहचान, एक ऑब्जेक्ट जिसमें email और/या phone_number होते हैं, जो create अनुरोध में दिए गए मानों से मेल खाते हैं। सत्यापन कोड का एक प्रयास जिस एक पते पर गया, उसे अपने address फ़ील्ड में बताता है
• metadata: create अनुरोध का मुक्त-रूप ऑब्जेक्ट, बिना बदलाव के लौटाया गया, या अनुरोध में कोई ऑब्जेक्ट न होने पर null

सेशन इवेंट

verify.verification.created

जैसे ही कोई सत्यापन बनाया जाता है और उसका पहला सत्यापन कोड कतार में डाला जाता है, यह इवेंट फ़ायर होता है। इसमें channel (वह चैनल जिस पर पहला प्रयास भेजा जा रहा है), status: "pending" और created_at जुड़ते हैं।

{
  "type": "verify.verification.created",
  "timestamp": "2026-07-23T14:45:58Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "channel": "sms",
    "to": { "phone_number": "+14155550100" },
    "status": "pending",
    "created_at": "2026-07-23T14:45:58Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.verification.verified

यह इवेंट तब फ़ायर होता है जब POST /v1/verify/verifications/check सही कोड की पुष्टि करता है। इसमें status: "verified", channel (वह चैनल जिसने जमा किया गया कोड डिलीवर किया, या null जब सत्यापन किसी चैनल को श्रेय दिए बिना पूरा हुआ) और verified_at जुड़ते हैं।

{
  "type": "verify.verification.verified",
  "timestamp": "2026-07-23T14:46:38Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "status": "verified",
    "channel": "sms",
    "verified_at": "2026-07-23T14:46:38Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.verification.failed

यह इवेंट तब फ़ायर होता है जब डिलीवरी योजना समाप्त हो जाती है और दर्ज विफलताएँ दिखाती हैं कि कोई सत्यापन कोड नहीं भेजा गया। पेलोड में status: "failed", reason: "undeliverable", channel (आज़माया गया अंतिम चैनल, या null जब किसी चैनल को श्रेय नहीं दिया गया), last_attempt_reason और failed_at जुड़ते हैं।

channel_unavailable, channel_disabled, channel_restricted और not_billable दिखाते हैं कि किसी प्रयास ने सत्यापन कोड नहीं भेजा। अगर किसी प्रयास ने कोड भेजा हो सकता है, तो बाद में होने वाला बाउंस, कैरियर द्वारा अस्वीकृति या डिलीवरी टाइमआउट सेशन को लंबित छोड़ देता है और कोई verify.verification.failed नहीं भेजता। पहले भेजा गया कोड समाप्त होने से पहले अब भी सत्यापित हो सकता है।

last_attempt_reason वही विफलता कारण इस्तेमाल करता है जो verify.attempt.undelivered करता है। not_billable विफलता का अर्थ है कि भेजने का शुल्क नहीं लिया जा सका; वर्कस्पेस का बैलेंस जाँचें और देखें कि गंतव्य के लिए मूल्य निर्धारण उपलब्ध है या नहीं।

डिलीवरी इवेंट

Bird जो भी सत्यापन कोड भेजता है, वह एक प्रयास है। दोबारा भेजना या चैनल फ़ेलओवर उसी verification_id के लिए एक और प्रयास बनाता है, जिसका अपना डिलीवरी क्रम होता है। किसी भी इवेंट में प्रयास पहचानकर्ता नहीं होता, और webhook-id उन्हें समूहित नहीं करेगा: यह एक इवेंट की एक डिलीवरी को पहचानता है, इसलिए एक ही प्रयास के sent और delivered में अलग-अलग मान होते हैं। उन्हें टाइमस्टैम्प क्रम में verification_id, channel और address के आधार पर जोड़ें। उसी चैनल पर दोबारा भेजने पर यह तरीका काम नहीं करता, क्योंकि उसके इवेंट केवल टाइमस्टैम्प में अलग होते हैं।

verify.attempt.sent

यह इवेंट तब फ़ायर होता है जब Bird सत्यापन कोड चैनल को सौंप देता है। इसमें channel, address (वह एकल पता जिस पर यह प्रयास भेजा गया, E.164 फ़ोन नंबर या ईमेल पता), from (भेजने वाला पता या नंबर, या null जब चैनल कोई प्रेषक नहीं दिखाता) और sent_at जुड़ते हैं।

{
  "type": "verify.attempt.sent",
  "timestamp": "2026-07-23T14:45:59Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "from": "29999",
    "sent_at": "2026-07-23T14:45:59Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.attempt.delivered

यह तब ट्रिगर होता है जब चैनल पुष्टि करता है कि सत्यापन कोड प्राप्तकर्ता तक पहुँच गया। इसमें channel, address, carrier, mcc_mnc (संदेश संभालने वाला नेटवर्क और उसका मोबाइल कंट्री/नेटवर्क कोड) और delivered_at जुड़ते हैं। ईमेल, WhatsApp और Telegram के लिए carrier और mcc_mnc फ़ील्ड हमेशा null होते हैं। इस इवेंट में from नहीं होता; इसे उसी प्रयास के verify.attempt.sent से पढ़ें।

{
  "type": "verify.attempt.delivered",
  "timestamp": "2026-07-23T14:46:03Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "carrier": "Example Wireless",
    "mcc_mnc": "310260",
    "delivered_at": "2026-07-23T14:46:03Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.attempt.undelivered

यह तब ट्रिगर होता है जब चैनल सत्यापन कोड डिलीवर नहीं कर सका। इसमें channel, address, reason (एक खुला enum, जिसमें carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout और not_billable शामिल हैं), error (केवल दिखाने के लिए विवरण, या null) और failed_at जुड़ते हैं। verify.attempt.delivered की तरह, इस इवेंट में भी from नहीं होता।

{
  "type": "verify.attempt.undelivered",
  "timestamp": "2026-07-23T14:46:04Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "reason": "carrier_rejected",
    "error": "Carrier rejected the message before delivery",
    "failed_at": "2026-07-23T14:46:04Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

अगर प्राप्तकर्ता के लिए एक से अधिक चैनल उपलब्ध हैं, तो एक अनडिलीवर्ड प्रयास से सत्यापन समाप्त नहीं होता। Bird डिलीवरी प्लान के अगले चैनल पर चला जाता है, जिसे अपना verify.attempt.sent मिलता है। जो चैनल भेजने से पहले ही विफल हो जाता है, वह reason: "channel_unavailable" के साथ verify.attempt.undelivered भेजता है और इसी तरह आगे बढ़ता है। यही उस चैनल पर भी लागू होता है जो प्राप्तकर्ता के देश में सत्यापन कोड नहीं भेजता, और तब reason: "channel_restricted" आता है (देखें देश कॉन्फ़िगरेशन)। उस प्रयास का कोई verify.attempt.sent या बाद की डिलीवरी रिपोर्ट नहीं होती। Bird हर विफल प्रयास के लिए verify.attempt.undelivered भेजता है। अगर प्लान समाप्त हो जाए और दर्ज विफलताएँ बताएँ कि कोई सत्यापन कोड नहीं भेजा गया, तो वह सेशन के लिए verify.verification.failed भी भेजता है।

डिलीवरी रिपोर्ट संकेत देती हैं, गारंटी नहीं। कैरियर और मेलबॉक्स प्रदाता अलग-अलग बातों की और अलग-अलग गति से पुष्टि करते हैं। कुछ बाज़ारों में प्रयास इवेंट कुछ मिनट बाद आते हैं, या डिलीवरी और स्वीकृति में अंतर नहीं करते। प्राप्तकर्ता को कोड मिलने और उसके इस्तेमाल का निर्णायक संकेत verify.verification.verified को मानें।

वेबहुक

डैशबोर्ड के वेबहुक पेज से या वेबहुक API के ज़रिए किसी एंडपॉइंट को किसी भी verify.* टाइप के लिए सब्सक्राइब करें। वेबहुक गाइड में एंडपॉइंट बनाना, Standard Webhooks सिग्नेचर सत्यापित करना, फिर से प्रयास और विफल डिलीवरी को दोबारा चलाना शामिल है।

अगले कदम