Webhook: kabari alat lain tentang apa yang terjadi
Webhook mengirim pesan singkat ke alat lain saat sesuatu terjadi di proyek Anda: publikasi, entri formulir, atau record yang berubah. Halaman ini membahas cara menambahkannya, seperti apa pesannya, bagaimana pihak penerima dapat memeriksa keasliannya, dan apa yang terjadi saat pihak penerima sedang tidak aktif.
Apa itu webhook
Anggap ini proyek Anda yang menelepon layanan lain untuk memberi tahu apa yang baru terjadi. Anda memberi Briks sebuah alamat (URL dari alat lain), memilih peristiwa yang perlu didengar, dan setiap kali peristiwa itu terjadi Briks mengirim pesan ke sana. Banyak alat otomatisasi, alat daftar klien, dan add on spreadsheet dapat memberi Anda alamat seperti itu.
Secara teknis, setiap pesan adalah permintaan POST: panggilan yang membawa isi pesan, di sini ditulis dalam JSON, format teks biasa yang dibaca program. Alat penerima membaca isinya dan melakukan apa yang sudah Anda atur.
| Peristiwa, seperti yang ditampilkan studio | Kode | Dikirim saat |
|---|---|---|
| Published | site.published | Versi baru situs telah tayang. |
| Form received | form.received | Seorang pengunjung mengirim pesan lewat salah satu formulir situs. |
| Record changed | record.changed | Sebuah rekaman di database proyek ditambahkan, diubah, atau dihapus. |
record.changed mengikuti perubahan yang dibuat di studio: record yang ditambahkan, diedit atau dihapus di tab Database, koleksi yang dikosongkan, atau database yang dipulihkan. Record yang disimpan sendiri oleh situs live, seperti permintaan pemesanan yang dikirim pengunjung, tidak memicunya.
form.received dikirim untuk entri dari pratinjau maupun dari produksi. Setiap pesan menyebutkan asalnya, sehingga alat lain dapat melewati entri dari pratinjau.
Batas di setiap paket
| Paket | Webhook per proyek | Panggilan per hari untuk setiap proyek |
|---|---|---|
| Free | 1 | 2,000 |
| Starter | 5 | 5.000 |
| Pro | 10 | 10,000 |
| Studio | 25 | 50.000 |
| Agency | 50 | 100.000 |
Ketika panggilan hari itu habis, pengiriman tidak dikirim dan ditandai Failed dengan pesan: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.
Setelah sebuah proyek memiliki webhook sebanyak yang diizinkan paketnya, Add webhook menjadi abu-abu dan tautan Get more di samping jumlahnya membuka jendela upgrade, yang menyebutkan paket terkecil dengan ruang untuk satu lagi.
Tambahkan webhook
Tekan Add webhook
Di mana: Settings, Webhooks
Halaman ini menunjukkan jumlah yang Anda miliki dibandingkan paket Anda, misalnya 1 dari 5 di paket Anda. Editor, Admin dan Owner dapat menambahkan webhook.
Masukkan alamat
Di mana: Add a webhook
Tempel alamat yang diberikan alat lain ke Address. Alamat itu harus berupa alamat https publik, dengan nama yang ditulis lengkap, bukan angka.
Tambahkan catatan
Di mana: Add a webhook
Note bersifat opsional, maksimal 120 karakter, dan membantu Anda membedakan webhook nanti, misalnya
Enquiries sheet.Pilih peristiwanya
Di mana: Add a webhook
Centang peristiwa yang ingin didengarnya. Published dan Form received sudah tercentang sejak awal; ubah sesuai kebutuhan.
Simpan dan salin secret
Di mana: Your signing secret
Tekan Add webhook. Sebuah dialog menampilkan rahasia penandatanganan, yang diawali dengan
whsec_. Tekan Copy dan simpanlah: rahasia ini hanya ditampilkan sekali. Lalu tekan Done.Kirim tes
Di mana: Settings, Webhooks
Buka tiga titik pada webhook dan pilih Send a test event. Anda akan melihat: A test event is on its way. See how it went under Deliveries.
Setiap webhook dalam daftar menampilkan alamat, catatan, dan peristiwanya, rahasia mana yang dipakai untuk menandatanganinya (beberapa karakter pertama), serta bagaimana pengiriman terakhirnya berjalan. Sakelarnya menyalakannya On atau Off, dan tiga titiknya berisi Send a test event (hingga sepuluh per jam, hanya saat webhook menyala), Change, New signing secret dan Delete.
Seperti apa sebuah pengiriman
Setiap pengiriman memiliki tiga bagian yang sama: type (kode peristiwa), timestamp (waktu kejadian, dalam UTC) dan data (rinciannya). Berikut contoh entri formulir:
{"type":"form.received","timestamp":"2026-10-08T09:41:07.000Z","data":{"form":{"id":"…","subject":"Pertanyaan pernikahan","page":"/contact","fields":[{"label":"Nama","value":"Ellie Marsh"},{"label":"Tanggal pernikahan","value":"14 Juni 2027"}],"replyTo":"ellie@example.com"},"production":true}}
| Acara | Isi data |
|---|---|
form.received | form: id, subject, page asal pengiriman, fields (masing-masing berisi label dan value, sesuai urutan formulir) dan replyTo, yaitu email pengunjung jika formulir memintanya. Lalu production: true untuk situs yang aktif, false untuk pratinjau. |
site.published | url: alamat tempat situs tayang. production: apakah situs berada di produksi. abTest: apakah uji A/B sedang berjalan. served: apakah Briks melihat versi baru menjawab di alamat itu saat mengirim pesan. |
record.changed | action: created, updated, deleted, cleared atau restored. collection: koleksi yang mana. record: id record. Nilai record tidak disertakan. |
test | Sebuah message dan project, beserta id dan name-nya. Dikirim hanya saat Anda menekan Send a test event. |
Setiap pengiriman juga membawa tiga header: webhook-id (id pesan), webhook-timestamp (waktu dikirim, dalam detik) dan webhook-signature. Header ini mengikuti format terbuka Standard Webhooks, sehingga alat yang memahaminya dapat memeriksa pengiriman untuk Anda.
Pastikan sebuah pengiriman asli
Siapa pun bisa mengirim pesan ke sebuah alamat, jadi pihak penerima sebaiknya memeriksa tanda tangan sebelum memercayainya. Tanda tangan dibuat dengan signing secret yang hanya dimiliki Anda dan Briks. Setelah sebuah proyek punya webhook, halaman Webhooks menampilkan contoh kode singkat di bawah Checking a delivery is genuine. Secara garis besar, pemeriksaannya berjalan seperti ini:
- Ambil isi permintaan persis seperti yang diterima, sebagai teks, sebelum dibaca sebagai JSON.
- Gabungkan
webhook-id,webhook-timestamp, dan isi pesan dengan tanda titik di antaranya. - Ambil secret Anda, hapus
whsec_di awalnya, lalu dekode sisanya dari base64. Itulah kuncinya. - Tanda tangani teks gabungan itu dengan HMAC SHA-256 dan kunci tersebut, tulis hasilnya dalam base64, lalu taruh
v1,di depannya. - Pengiriman dinyatakan asli jika cocok dengan salah satu nilai yang dipisahkan spasi di
webhook-signature, dan stempel waktunya berada dalam lima menit dari sekarang.
Pengiriman yang dicoba lagi tetap memakai webhook-id yang sama, sehingga penerima dapat menyimpan id yang sudah ditangani dan melewati pengulangan.
Pengiriman dan percobaan ulang
Deliveries mencantumkan setiap pengiriman dalam tiga puluh hari terakhir, dari yang terbaru. Persempit dengan Status lalu tekan Show. Klik salah satu untuk melihat pesan lengkap, error jika ada, dan jawaban dari alamat tujuan.
| Status | Arti |
|---|---|
| Sending | Menunggu percobaan pertamanya. |
| Retrying | Satu percobaan gagal dan percobaan lain akan menyusul. Baris ini menunjukkan kapan, setelah percobaan berikutnya. |
| Delivered | Alamat itu menjawab dengan status 2xx, kode keberhasilan di web. |
| Failed | Setiap percobaan gagal, atau pengiriman tidak dapat dikirim sama sekali. |
Setiap percobaan menunggu jawaban hingga 15 detik. Jika jawabannya bukan 2xx, Briks mencoba lagi: lima kali percobaan, yang pertama langsung, lalu setelah sekitar 30 detik, 2 menit, 8 menit, dan 32 menit, jadi sekitar 45 menit dari yang pertama hingga yang terakhir. Jawaban 410 (gone) menghentikan percobaan ulang seketika. Pengalihan tidak diikuti, jadi berikan alamat akhirnya.
Setelah sebuah pengiriman berstatus Failed atau Delivered, Send again mengirim pesan yang sama dengan id yang sama, dengan tanda tangan baru. Webhook harus dalam keadaan aktif.
Wawasan dan pengaturan
Insights merangkum tiga puluh hari terakhir: Deliveries, persentase Delivered, Failed after every try (beserta jumlah percobaan ulang yang dilakukan), dan waktu Average answer. Di bawahnya, By event dan By address menunjukkan di mana kegagalan terkumpul.
Settings memiliki Download JSON di bawah Download the webhooks, berisi alamat, event, dan catatan setiap webhook. Rahasia penandatanganan tidak pernah disertakan. Zona berbahayanya memuat Clear log, yang menghapus log pengiriman dan menghentikan semua percobaan ulang, serta Delete all, yang menghapus setiap webhook setelah Anda mengetik nama proyek. Keduanya untuk Owner dan Admin.
Contoh kasus: entri formulir ke alat lain
Entri formulir tidak bisa diekspor dari studio, jadi webhook adalah cara untuk menyimpannya di alat lain begitu masuk. Studio juga menyimpannya: 100 entri terbaru tampil di Settings, Forms.
Seorang fotografer pernikahan di York mengirim pertanyaan masuk ke daftar kliennya
Ambil alamat dari alat lain
Di mana: Her client list tool
Di sana ia membuat incoming webhook dan menyalin alamat yang diberikan.
Tambahkan webhook
Di mana: Settings, Webhooks
Ia menempelkan alamatnya, menulis catatan
Client list, menghapus centang Published, dan hanya menyisakan centang pada Form received.Berikan rahasia itu kepada alat
Di mana: Her client list tool
Alatnya memeriksa tanda tangan, jadi ia menempelkan signing secret ke pengaturannya sebelum menutup dialog.
Cobalah
Di mana: Settings, Webhooks, Deliveries
Ia mengirim event uji dan melihatnya berstatus Delivered di bawah Deliveries.
Cocokkan kolomnya
Di mana: Her client list tool
Dia memetakan label
fieldsName, Wedding date, dan Venue ke kolom di alatnya, dan menyuruhnya mengabaikan pesan yangproduction-nyafalse.
Sepasang pengunjung mengisi formulir kontak di situs live miliknya.
Pertanyaan itu masuk ke kotak masuknya, karena situs sudah dalam produksi, dan muncul di daftar kliennya beberapa saat kemudian.