Verify इवेंट

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

इवेंट	अक्ष	कब ट्रिगर होता है
verify.verification.created	सेशन	सत्यापन बनाया गया और पहला सत्यापन कोड भेजने के लिए क्यू किया गया
verify.attempt.sent	डिलीवरी	सत्यापन कोड डिलीवरी के लिए चैनल को सौंपा गया
verify.attempt.delivered	डिलीवरी	चैनल ने पुष्टि की कि सत्यापन कोड प्राप्तकर्ता तक पहुँचा
verify.attempt.undelivered	डिलीवरी	चैनल सत्यापन कोड प्राप्तकर्ता तक नहीं पहुँचा सका
verify.verification.verified	सेशन	प्राप्तकर्ता ने सत्यापन समाप्त होने से पहले सही कोड सबमिट किया
verify.verification.failed	सेशन	डिलीवरी प्लान विफलताओं के साथ समाप्त हुआ जो दर्शाती हैं कि कोई सत्यापन कोड नहीं भेजा गया

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

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

इवेंट एन्वेलप

इवेंट आपके webhook एंडपॉइंट पर Standard Webhooks के नेस्टेड एन्वेलप में आते हैं, जो 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 दर्शाते हैं कि प्रयास ने सत्यापन कोड नहीं भेजा। यदि प्रयास ने भेजा हो सकता है, तो बाद में बाउंस, कैरियर अस्वीकृति, या डिलीवरी टाइमआउट सेशन को pending रखता है और कोई verify.verification.failed emit नहीं करता। पहले भेजा गया कोड समाप्त होने से पहले अभी भी सत्यापित हो सकता है।

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 जब चैनल कोई sender उजागर नहीं करता), और 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 (हैंडलिंग नेटवर्क और उसका मोबाइल country/network कोड), और delivered_at जुड़ते हैं। carrier और mcc_mnc फ़ील्ड email, WhatsApp, और Telegram के लिए हमेशा 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 मिलता है। भेजने से पहले विफल होने वाला चैनल verify.attempt.undelivered को reason: "channel_unavailable" के साथ emit करता है और उसी तरह आगे बढ़ता है, जैसा कि वह चैनल जो प्राप्तकर्ता के देश में सत्यापन कोड नहीं ले जाता, reason: "channel_restricted" के साथ (देखें देश कॉन्फ़िगरेशन)। उस प्रयास का कोई verify.attempt.sent या बाद की डिलीवरी रिपोर्ट नहीं होती। Bird हर विफल प्रयास के लिए verify.attempt.undelivered emit करता है। यदि प्लान समाप्त हो गया है और दर्ज विफलताएँ दर्शाती हैं कि कोई सत्यापन कोड नहीं भेजा गया, तो यह सेशन के लिए verify.verification.failed भी emit करता है।

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

Webhooks

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

अगले कदम

पेज	क्या शामिल है
सत्यापन भेजना	भेजने और जाँच कॉल, स्टेटस, सेटिंग्स, और सीमाएँ
Webhooks और इवेंट	एंडपॉइंट सेटअप, सिग्नेचर सत्यापन, फिर से प्रयास, और रीप्ले
API रेफ़रेंस: सत्यापन बनाएँ	भेजने वाले एंडपॉइंट का स्कीमा और त्रुटि विवरण

संबंधित संसाधन