Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

Event Verify

Sebuah verifikasi menghasilkan event untuk sesi dan setiap percobaan pengiriman. Sesi dimulai saat Bird membuat verifikasi dan berkonversi saat penerima memasukkan kode yang benar. Setiap pengiriman kode verifikasi membuat satu percobaan pada satu channel, yang bisa terkirim atau tidak terkirim. Pengiriman ulang dan failover channel menambahkan percobaan ke sesi yang sama.
EventSumbuTerjadi ketika
verify.verification.createdSesiVerifikasi dibuat dan kode verifikasi pertama diantrikan untuk dikirim
verify.attempt.sentPengirimanKode verifikasi telah diserahkan ke channel untuk pengiriman
verify.attempt.deliveredPengirimanChannel mengonfirmasi kode verifikasi sampai ke penerima
verify.attempt.undeliveredPengirimanChannel tidak dapat mengirimkan kode verifikasi ke penerima
verify.verification.verifiedSesiPenerima mengirimkan kode yang benar sebelum verifikasi kedaluwarsa
verify.verification.failedSesiRencana pengiriman berakhir dengan kegagalan yang menunjukkan tidak ada kode verifikasi yang terkirim
Verifikasi yang tidak berhasil dikonversi tidak pernah mengeluarkan verify.verification.verified, dan status-nya saja tidak memberi tahu Anda alasannya. failed bersifat umum: verifikasi berakhir di sana baik ketika terlalu banyak kode verifikasi salah yang dikirimkan, dengan reason attempts_exhausted, maupun ketika rencana pengiriman berakhir dengan kegagalan yang menunjukkan tidak ada kode verifikasi yang terkirim, dengan reason undeliverable. Hanya yang kedua yang mengeluarkan verify.verification.failed, dan event tersebut selalu membawa reason undeliverable, sehingga event itulah yang membedakan keduanya saat status tidak bisa. Jendela validitas yang habis berubah menjadi expired. Baik expired maupun failed yang kehabisan percobaan tidak mengeluarkan event-nya sendiri. Channel fallback membuat verify.attempt.sent-nya sendiri, sehingga satu verifikasi dapat memiliki beberapa urutan percobaan.
Daftar tipe event bersifat terbuka: tipe baru dapat ditambahkan sewaktu-waktu, jadi perlakukan nilai yang tidak dikenal sebagai event baru, bukan error.

Envelope event

Event tiba di endpoint webhook Anda dalam envelope bersarang Standard Webhooks yang dijelaskan di Panduan Webhooks: sebuah type, sebuah timestamp, dan objek data khusus tipe. Identitas event tidak ada di body: ia berada di header webhook-id HTTP, yang stabil di seluruh percobaan ulang pengiriman yang sama dan merupakan kunci deduplikasi Anda.
data setiap event membawa basis identitas berikut:
  • verification_id: verifikasi yang terkait dengan event ini, cocok dengan id dari POST /v1/verify/verifications
  • workspace_id: workspace yang membuat verifikasi
  • to: identitas penerima verifikasi, sebuah objek dengan email dan/atau phone_number yang cocok dengan apa yang diberikan permintaan pembuatan. Satu percobaan kode verifikasi melaporkan alamat tujuannya di field address sendiri
  • metadata: objek bebas dari permintaan pembuatan, diteruskan tanpa perubahan, atau null jika permintaan tidak menyertakannya

Event sesi

verify.verification.created

Dipicu segera setelah verifikasi dibuat dan kode verifikasi pertamanya diantrikan. Menambahkan channel (channel yang digunakan percobaan pertama), status: "pending", dan created_at.
Contoh kode
{
  "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

Dipicu saat POST /v1/verify/verifications/check mengonfirmasi kode yang benar. Menambahkan status: "verified", channel (channel mana pun yang mengirimkan kode yang dikirimkan, atau null jika verifikasi diselesaikan tanpa mengatribusikan channel), dan verified_at.
Contoh kode
{
  "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

Dipicu ketika rencana pengiriman habis dan kegagalan yang tercatat menunjukkan tidak ada kode verifikasi yang terkirim. Payload menambahkan status: "failed", reason: "undeliverable", channel (channel terakhir yang dicoba, atau null jika tidak ada yang diatribusikan), last_attempt_reason, dan failed_at.
channel_unavailable, channel_disabled, channel_restricted, dan not_billable menunjukkan bahwa percobaan tidak mengirimkan kode verifikasi. Jika percobaan mungkin telah mengirimkannya, bounce, penolakan operator, atau timeout pengiriman berikutnya membiarkan sesi tetap pending dan tidak mengeluarkan verify.verification.failed. Kode sebelumnya masih dapat diverifikasi sebelum kedaluwarsa.
last_attempt_reason menggunakan alasan kegagalan yang sama dengan verify.attempt.undelivered. Kegagalan not_billable berarti pengiriman tidak dapat dikenakan biaya; periksa saldo workspace dan apakah harga tersedia untuk tujuan tersebut.

Event pengiriman

Setiap kode verifikasi yang dikirim Bird adalah satu percobaan. Pengiriman ulang atau failover channel membuat percobaan lain terhadap verification_id yang sama, dengan urutan pengirimannya sendiri. Tidak ada event yang membawa identifier percobaan, dan webhook-id tidak akan mengelompokkannya: ia mengidentifikasi satu pengiriman dari satu event, sehingga sent dan delivered untuk satu percobaan membawa nilai yang berbeda. Pasangkan berdasarkan verification_id, channel, dan address dalam urutan waktu. Pengiriman ulang pada channel yang sama adalah kasus yang mengalahkan cara ini, karena event-nya hanya berbeda berdasarkan timestamp.

verify.attempt.sent

Dipicu setelah Bird menyerahkan kode verifikasi ke channel. Menambahkan channel, address (alamat tunggal tujuan pengiriman percobaan ini, nomor telepon E.164 atau alamat email), from (alamat atau nomor pengirim, null jika channel tidak mengekspos pengirim), dan sent_at.
Contoh kode
{
  "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

Dipicu ketika channel mengonfirmasi kode verifikasi sampai ke penerima. Menambahkan channel, address, carrier, mcc_mnc (jaringan yang menangani beserta kode negara/jaringan selulernya), dan delivered_at. Field carrier dan mcc_mnc selalu null untuk email, WhatsApp, dan Telegram. Event ini tidak menyertakan from; baca dari verify.attempt.sent untuk percobaan yang sama.
Contoh kode
{
  "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

Dipicu ketika channel tidak dapat mengirimkan kode verifikasi. Menambahkan channel, address, reason (enum terbuka termasuk carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout, dan not_billable), error (detail tampilan saja, atau null), dan failed_at. Seperti verify.attempt.delivered, event ini tidak menyertakan from.
Contoh kode
{
  "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" }
  }
}
Percobaan yang gagal terkirim pada penerima dengan lebih dari satu channel yang tersedia tidak mengakhiri verifikasi. Bird melanjutkan ke channel berikutnya dalam rencana pengiriman, yang mendapatkan verify.attempt.sent-nya sendiri. Channel yang gagal sebelum mengirim mengeluarkan verify.attempt.undelivered dengan reason: "channel_unavailable" dan melanjutkan dengan cara yang sama, begitu juga channel yang tidak mengirimkan kode verifikasi ke negara penerima, dengan reason: "channel_restricted" (lihat Konfigurasi negara). Percobaan tersebut tidak memiliki verify.attempt.sent atau laporan pengiriman selanjutnya. Bird mengeluarkan verify.attempt.undelivered untuk setiap percobaan yang gagal. Jika rencana habis dan kegagalan yang tercatat menunjukkan tidak ada kode verifikasi yang terkirim, ia juga mengeluarkan verify.verification.failed untuk sesi tersebut.
Laporan pengiriman bersifat indikatif, bukan dijamin. Operator dan penyedia kotak masuk bervariasi dalam apa yang mereka konfirmasi dan seberapa cepat. Di beberapa pasar, event percobaan tiba beberapa menit kemudian atau tidak membedakan pengiriman dari penerimaan. Perlakukan verify.verification.verified sebagai sinyal definitif bahwa penerima telah menerima dan menggunakan kode mereka.

Webhook

Daftarkan endpoint ke tipe verify.* apa pun dari halaman Webhooks di dashboard atau melalui API webhook. Panduan Webhooks membahas pembuatan endpoint, verifikasi tanda tangan Standard Webhooks, coba lagi, dan memutar ulang pengiriman yang gagal.

Langkah selanjutnya

HalamanApa yang dibahas
Mengirim verifikasiPanggilan kirim dan periksa, status, pengaturan, dan batas
Webhook & eventPengaturan endpoint, verifikasi tanda tangan, coba lagi, dan putar ulang
Referensi API: membuat verifikasiSkema endpoint pengiriman dan detail kesalahan

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaVerify phone numbers at signupPahami konsepnyaWhat does OTP mean? One-time passwords explainedJelajahi kemampuannyaCustomer verificationIkuti jalur pembelajaranBuild your first integration
Coba praktiknya dan dapatkan ringkasan implementasi