URL callback SMS
URL callback menerima event dari satu pesan SMS, atau dari setiap pesan pada profil pesan, sebagai pengganti endpoint webhook Anda. Gunakan URL callback jika sebuah pesan atau program memerlukan penerimanya sendiri.
Kelola secret penandatanganan, riwayat percobaan, dan pemutaran ulang di dashboard, atau melalui API dan perintah bird webhooks callbacks. Tetapkan URL profil saat Anda membuat profil pesan atau memperbaruinya.
Pilih tujuan event
URL ditentukan satu kali, saat pesan diterima, lalu digunakan selama masa hidup pesan tersebut. Perubahan pada profil setelahnya tidak mengubah rute pesan yang sedang diproses.
| Pesan | URL yang digunakan |
|---|---|
Dikirim dengan options.callback_url | URL tersebut |
Dikirim dengan options.callback_url bernilai null | Tidak ada: event dikirim ke endpoint webhook Anda |
| Dikirim tanpanya, melalui profil pesan | options.callback_url milik profil tersebut |
| Diterima di nomor milik profil pesan | inbound.callback_url milik profil tersebut, lalu options.callback_url miliknya |
| Tidak ada URL dari semua sumber di atas | Tidak ada: event dikirim ke endpoint webhook Anda |
URL harus berupa HTTPS, paling panjang 2.048 karakter, dan berupa alamat publik. Host privat, loopback, atau link-local menghasilkan 422.
Daftar percobaan callback menunjukkan tujuan pengiriman event dari pesan yang diterima.
Apa yang digantikan oleh URL
Selama URL berlaku, event pesan tersebut tidak dikirim ke endpoint webhook Anda. Pesan lain di workspace tetap mencapai endpoint tersebut. Callback yang gagal tidak dialihkan kembali ke endpoint Anda: gunakan pemutaran ulang untuk memulihkannya.
Langganan MCP Events dan endpoint konektor tetap menerima event pesan tersebut.
callback_events pada profil pesan menentukan event keluar mana yang dikirim ke URL, dari sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected, dan sms.expired. Event yang tidak tercantum dalam daftar juga tidak mencapai endpoint webhook mana pun untuk pesan tersebut. Profil tanpa daftar, dan pengiriman tanpa profil, mengirimkan setiap event keluar. sms.received tidak pernah difilter. Payload-nya adalah event SMS.
Verifikasi tanda tangan
Callback menggunakan header Standard Webhooks dan tanda tangan HMAC-SHA256 yang sama dengan endpoint webhook, sehingga kode verifikasi yang sudah Anda miliki tetap berfungsi tanpa perubahan. Kuncinya adalah secret penandatanganan callback milik workspace Anda, yaitu satu secret yang digunakan bersama oleh semua URL callback dan semua permintaan webhook voice sequence, sehingga rotasi berlaku untuk keduanya.
Secret pertama tidak pernah ditampilkan. Rotasikan secret di Webhooks → Direct callbacks pada dashboard atau dengan Rotate callback signing secret untuk mendapatkan secret yang dapat Anda gunakan. Secret baru hanya ditampilkan satu kali, jadi simpan sebelum Anda meninggalkan halaman. Selama 24 jam berikutnya, setiap callback ditandatangani dengan secret lama dan secret baru, sehingga Anda dapat menerapkan secret baru tanpa kehilangan pengiriman. Satu workspace dapat memiliki paling banyak 5 secret yang berlaku bersamaan, sehingga rotasi berikutnya selama masa tumpang tindih ini dapat ditolak. Rotasi mulai berlaku dalam waktu sekitar satu menit.
Rotasikan secret sebelum Anda mengandalkan verifikasi: sampai Anda melakukannya, callback membawa tanda tangan yang dibuat dengan secret yang tidak dapat Anda lihat.
Percobaan ulang dan duplikat
Callback mengikuti jadwal percobaan ulang endpoint webhook: delapan percobaan selama sekitar 27,5 jam, dan 2xx dalam 15 detik dihitung sebagai berhasil. Berbeda dengan endpoint, URL callback tidak pernah dijeda.
Pengiriman dilakukan setidaknya sekali dan tidak berurutan. Hapus duplikat berdasarkan header webhook-id, lalu urutkan berdasarkan timestamp di dalam payload.
Temukan dan putar ulang callback yang gagal
Tab Direct callbacks di bawah Webhooks pada dashboard, serta List callback delivery attempts, menampilkan percobaan callback di workspace, dari yang terbaru, beserta URL, status yang dikembalikan penerima Anda, dan latensinya. Percobaan disimpan selama tiga hari.
Replay failed callback deliveries menjadwalkan satu percobaan tambahan untuk setiap event yang callback-nya gagal dalam rentang waktu yang Anda pilih, seperti pemutaran ulang pengiriman endpoint untuk endpoint. Event yang juga berhasil dikirim dalam rentang tersebut dilewati. Keberhasilan di luar rentang tidak dihitung, sehingga event tersebut dikirim lagi. Satu pemutaran ulang mengirim paling banyak 10.000 event gagal terlama dalam rentang tersebut; setelah gangguan yang lebih lama, putar ulang lagi dengan waktu mulai yang lebih akhir untuk sisanya.
Pemutaran ulang mengirim ke URL yang tercatat pada percobaan yang gagal, bukan ke endpoint webhook Anda dan bukan ke URL profil saat ini. Pemutaran ulang memulihkan gangguan pada penerima Anda. Pemutaran ulang tidak dapat memulihkan pesan yang dikirim ke URL yang salah, jadi kirim ulang pesan tersebut. Pemutaran ulang dihitung dalam batas harian yang sama dengan pemutaran ulang endpoint.
Langkah berikutnya
- Event SMS: payload setiap event
- Webhook & event: tanda tangan, percobaan ulang, dan pemutaran ulang secara lengkap
- Mengirim SMS: permintaan pengiriman
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.