URL penerima yang bersifat publik dapat menerima permintaan dari siapa saja. Penyerang dapat mengirim event palsu ke URL tersebut, sehingga permintaan perlu diautentikasi sebelum memicu proses.
Bird menggunakan skema penandatanganan Standard Webhooks. Skema ini mengautentikasi identifier event dan waktu percobaan bersama body, sehingga mengubah salah satunya akan membatalkan tanda tangan.
Apa yang ditandatangani Bird?
Bird menandatangani identifier event, timestamp percobaan pengiriman, dan body permintaan mentah yang digabungkan dengan titik.
Pertahankan body permintaan tanpa perubahan sampai Anda memverifikasi tanda tangan. Parsing dan serialisasi JSON dapat mengubah byte yang ditandatangani Bird.
| Header | Isi |
|---|---|
webhook-id | Identifier event, digunakan ulang pada percobaan ulang dan replay. |
webhook-timestamp | Waktu percobaan sebagai Unix timestamp dalam detik. |
webhook-signature | Satu atau lebih tanda tangan, dipisahkan spasi. Masing-masing diawali v1,. |
Konversi timestamp dari detik sebelum membandingkannya dengan clock yang melaporkan milidetik.
Hapus prefiks whsec_ dari secret endpoint Anda dan decode base64 sisanya untuk mendapatkan byte kunci.
Gabungkan identifier, timestamp, dan body yang belum diubah dengan titik. Hitung HMAC-SHA256 atas string tersebut menggunakan kunci yang sudah di-decode. Bandingkan hasilnya dengan setiap tanda tangan yang diberikan menggunakan perbandingan constant-time, yang waktu eksekusinya tidak mengungkapkan byte mana yang cocok.
Mengapa tanda tangan saya tidak pernah cocok?
Secret yang salah atau body permintaan yang berubah dapat membuat setiap pemeriksaan tanda tangan gagal.
Framework web sering kali mem-parse JSON sebelum handler Anda dijalankan. Menyerialisasi objek tersebut kembali dapat mengubah whitespace, urutan key, atau format angka. JSON yang dihasilkan bisa bermakna sama tetapi menghasilkan tanda tangan yang berbeda.
Konfigurasikan route ini untuk mempertahankan body mentahnya. Pastikan secret tersebut milik endpoint ini, terutama setelah deployment atau rotasi.
Apa yang harus ditolak handler saya?
Tolak permintaan jika tidak ada tanda tangan yang cocok atau timestamp yang ditandatangani berada di luar jendela waktu yang diizinkan.
Coba setiap tanda tangan di webhook-signature. Selama rotasi secret, pengiriman membawa tanda tangan dari beberapa secret yang valid. Menerima tanda tangan mana pun yang cocok memungkinkan penerima yang menggunakan salah satu secret tetap bekerja.
Gunakan toleransi timestamp lima menit di kedua sisi clock Anda. Permintaan yang dicegat dari sepuluh menit sebelumnya akan gagal meskipun tanda tangannya tidak berubah. Jaga clock server Anda tetap akurat agar tidak menolak pengiriman yang sah.
Periksa webhook-id terhadap event yang sudah Anda simpan. Duplikat yang dikenali harus menerima respons sukses tanpa mengulangi prosesnya, karena mencoba ulang pengiriman yang sama tidak menambahkan event baru.
Apa yang terjadi jika saya menolak pengiriman?
Bird mencoba ulang pengiriman yang menerima respons error atau tidak ada respons sebelum timeout-nya.
Respons 400, misalnya, mencatat penolakan dan membiarkan pengiriman tetap layak untuk dicoba ulang. Semua respons non-2xx mengikuti kebijakan percobaan ulang. Kode tersebut membantu Anda mendiagnosis kegagalan di log Anda.
Jadwalnya mencakup sekitar 27,5 jam sebelum penyesuaian, memberi Anda waktu untuk memperbaiki secret yang salah. Percobaan ulang webhook yang gagal menjelaskan jadwal dan cara me-replay event yang terlewat setelahnya.
Kembalikan 2xx hanya setelah Anda memverifikasi dan menyimpan event dengan aman, atau mengenali duplikat yang sudah tersimpan. Bird melewati pengiriman yang berhasil saat replay, sehingga mengonfirmasi permintaan yang belum diverifikasi mencegah pemulihan melalui mekanisme tersebut.
Apakah saya harus mengimplementasikan verifikasi sendiri?
Anda tidak perlu mengimplementasikan verifikasi sendiri jika menggunakan webhooks.unwrap di Bird SDK. Berikan body mentah dan header permintaan kepadanya.
Helper memeriksa tanda tangan dan timestamp sebelum mengembalikan event yang sudah di-decode. Aplikasi Anda tetap mendeduplikasi berdasarkan webhook-id, karena aplikasi Anda yang memiliki catatan pekerjaan yang sudah selesai.
Library verifikasi Standard Webhooks yang kompatibel dapat melakukan pemeriksaan yang sama. Panduan webhooks menyertakan contoh dan implementasi manual.
Singkatnya
Verifikasi byte asli.
Parsing dan serialisasi JSON dapat mengubah byte yang ditandatangani Bird. Simpan body mentah untuk verifikasi.
Periksa waktu selain tanda tangan.
Toleransi timestamp lima menit membatasi penggunaan ulang permintaan yang dicegat. Deduplikasi event yang tersimpan berdasarkan webhook-id secara terpisah.
Coba setiap tanda tangan yang diberikan.
Rotasi menghasilkan tanda tangan yang tumpang tindih. Kecocokan dengan tanda tangan valid mana pun memungkinkan deployment tetap berjalan.
Konfirmasi hanya event yang terverifikasi dan tersimpan.
Bird mencoba ulang respons non-2xx dan melewati pengiriman yang berhasil saat replay. Kembalikan sukses untuk duplikat yang sudah tersimpan tanpa mengulangi prosesnya.