Webhook mengirimkan data ke URL pilihan Anda tepat saat sesuatu terjadi, misalnya saat seseorang berpartisipasi dalam kampanye atau memenangkan hadiah. Developer Anda yang menyiapkan sistem penerimanya.
Webhook tersedia di paket yang mencakup Webhooks & API (Basic ke atas).
Webhook kampanye atau webhook akun?
- Webhook kampanye diatur di editor kampanye dan hanya aktif untuk kampanye tersebut. Webhook ini memiliki event “Every time a lead participates in a campaign” dan “When a lead wins a prize”, serta opsi paling lengkap.
- Webhook akun diatur di Settings > Webhooks. Webhook ini memiliki event “When a new lead is created”: event ini aktif satu kali per orang, yaitu saat pertama kali orang tersebut ditambahkan ke lead Anda, dari kampanye mana pun asalnya.
Menambahkan webhook ke kampanye
- Buka kampanye di editor, lalu masuk ke Connect > Webhooks.
- Klik Add webhook.
- Masukkan Payload URL. URL harus diawali https: “We only support webhooks over HTTPS to ensure that the data sent remains secure.”
- Pilih Content type: application/json atau application/x-www-form-urlencoded.
- Pilih Method. Formulir diawali dengan GET, yang mengirim data di URL. Pilih POST untuk mengirimnya di body, yang umumnya diharapkan oleh kebanyakan sistem.
- Di bagian Authentication (hanya untuk POST), pilih Basic Auth jika URL Anda memerlukan nama pengguna dan kata sandi, lalu isi Username dan Password. Jika tidak, biarkan None.
- Masukkan Secret untuk menandatangani permintaan (disarankan). Lihat “Memeriksa tanda tangan” di bawah.
- Aktifkan Log response body jika Anda ingin melihat respons dari sistem Anda. “Enable to store the response body for debugging.”
- Biarkan Active tetap aktif. “We will only deliver events if the webhook is active.”
- Pilih event: “Every time a lead participates in a campaign” atau “When a lead wins a prize”.
- Aktifkan Custom payload jika Anda ingin menentukan field sendiri (lihat di bawah).
- Klik Add webhook. Anda akan melihat “Webhook added”.
Panel Webhooks menampilkan daftar webhook kampanye dengan status Active atau Inactive, serta Last delivery failed jika permintaan terakhir gagal. Gunakan Actions untuk Edit, See deliveries, atau Delete webhook. Saat mengedit webhook, kosongkan Secret untuk mempertahankan secret yang sudah ada.
Menambahkan webhook akun
- Buka Settings > Webhooks (di bawah Developers). Webhook Anda tercantum di My webhooks (atau di bawah nama setiap daftar lead, jika Anda memiliki beberapa).
- Klik kartu bertanda plus untuk menambahkan webhook. Dialog Add webhook menampilkan “Send a request to an external URL whenever selected events happen.”
- Isi Payload URL, Content type (“Select content type of the webhook”), Method, dan Secret seperti di atas.
- Di bagian Which events should trigger the webhook?, pilih “When a new lead is created”.
- Centang “Yes, allow me to specify a customized payload (Advanced users only)” jika Anda ingin menggunakan field sendiri.
- Centang Log response body (“This webhook will log the response body”) jika perlu, dan biarkan Active tetap tercentang (“We will deliver event details when this hook is triggered”).
- Klik Add webhook.
Klik webhook untuk mengubahnya (Simpan perubahan), menetapkan New secret, membuka Show deliveries, atau Delete webhook (“This action cannot be reverted!”).
Data yang dikirim
Secara default, body berisi event (nama event: lead_created_on_campaign, new_campaign_winner, atau lead_created) dan objek data:
campaign:iddannamekampanye (webhook kampanye)lead: field formulir lead berdasarkan kunci field-nya (misalnyafirst_name), ditambahid,phone_number, dancreated_atlead.permissions: untuk setiap kotak centang persetujuan, apakah disetujui, teksnya, tanggalnya, dan alamat IP-nya (webhook kampanye)participant:channelasal orang tersebut dan waktu ia berpartisipasi (webhook kampanye)quiz: jawaban atas pertanyaan kuis yang diberi nama, juga dengan nama yang mudah dibaca dan diawali “Simple”prize:id,name,value,coupon_codehadiah, serta waktu hadiah dimenangkan (webhook pemenang)
Nilai kosong tidak disertakan, begitu pula persetujuan yang tidak diterima. Dengan metode GET, data yang sama dikirim sebagai parameter kueri di URL.
Payload kustom
Jika Custom payload aktif, hanya field yang Anda pilih yang dikirim, dan tidak ada pembungkus event.
- Di bagian Data mapping, klik Add mapping.
- Ketik Field name yang diharapkan sistem Anda. Gunakan huruf, angka, tanda hubung, dan garis bawah.
- Pilih field Scratcher yang akan dikirim (“Group → Field”), atau Custom value lalu ketik Value tetap.
- Ulangi untuk setiap field. Hapus field dengan ikon tempat sampah (Remove atau Remove data mapping).
Memeriksa tanda tangan
Jika Anda menetapkan secret, setiap permintaan memiliki header X-Hub-Signature: sha1= diikuti hash HMAC-SHA1 dari payload berenkode JSON (body seperti dijelaskan di atas), dengan secret Anda sebagai kuncinya. Hitung hal yang sama di sisi Anda lalu bandingkan untuk memastikan permintaan benar-benar berasal dari Scratcher.
Pengiriman dan percobaan ulang
- Jika URL Anda tidak merespons atau mengembalikan error (status 400 atau lebih tinggi), Scratcher akan mencoba lagi dua kali: setelah 5 detik dan setelah satu menit.
- Pengalihan (redirect) tidak diikuti, jadi gunakan URL akhir.
- Buka daftar pengiriman (See deliveries di kampanye, Show deliveries untuk webhook akun) untuk melihat setiap permintaan dan respons. Setiap pengiriman menampilkan ID, Request, dan Response beserta kode statusnya (serta Response body jika Anda mencatatnya). Gunakan copy untuk menyalin payload.
- Aktifkan Show only failed deliveries untuk melihat masalahnya saja. Bagian atas menampilkan “Failed deliveries in the last 60 days”.
- Klik Retry untuk mengirim ulang pengiriman: “The webhook is being resent.”
- “Webhook delivery logs are retained for 60 days.”
Pemecahan masalah
- “The ... field must use HTTPS.”: Payload URL diawali http. Gunakan https.
- Semua pengiriman gagal tanpa respons: URL tidak dapat dijangkau dari internet, misalnya alamat lokal atau internal. Gunakan URL publik.
- Sistem Anda tidak menerima data: metodenya GET, sehingga data ada di URL. Ganti ke POST.
- Field yang diharapkan sistem Anda tidak ada: field tersebut kosong, atau persetujuannya tidak diterima. Atur sistem Anda agar memperlakukan field yang tidak ada sebagai kosong.