Webhook

Bayangkan Anda menjalankan toko pakaian online. Setiap kali Anda mendaftarkan produk baru, ada pekerjaan lanjutan yang harus selalu Anda urus sendiri. Misalnya menerjemahkan deskripsi produk ke bahasa negara lain, atau memberi tahu rekan kerja melalui pesan internal bahwa produk telah didaftarkan. Pekerjaan lanjutan seperti ini tidak harus dikerjakan dengan tangan setiap kali. Anda bisa membuatnya agar saat produk didaftarkan, sistem otomatis memberi tahu program di luar agar program itu yang mengerjakannya. "Alat yang otomatis memberi tahu tempat yang sudah ditentukan ketika sesuatu terjadi" inilah yang disebut Webhook.

Anda bisa membayangkannya seperti bel pintu yang dipasang di pintu toko. Saat pelanggan membuka pintu dan masuk (saat produk didaftarkan), bel berbunyi dengan sendirinya, sehingga karyawan di dalam (program di luar) langsung bergerak sambil berkata "Ada pelanggan datang". Tidak perlu ada orang yang terus mengawasi pintu. Seperti bel itu, Webhook secara otomatis memulai tindakan yang telah ditentukan tepat pada saat hal yang ditentukan terjadi.

Di halaman ini, Anda akan lebih dulu melihat apa itu Webhook dan dalam situasi apa ia digunakan, lalu membuat sendiri sebuah Webhook di Space toko pakaian.

Apa yang dilakukan Webhook

Webhook terdiri dari tiga hal yang ditentukan terlebih dahulu.

• Kapan: Anda menentukan hal apa yang harus terjadi agar ia bereaksi. Misalnya, bisa ditetapkan menjadi "ketika produk (Content) baru didaftarkan".
• Apa yang dikerjakan: Anda menentukan salah satu dari dua hal. Mengirim permintaan ke alamat internet (URL) program di luar, atau menjalankan Script yang telah Anda buat di dalam Space.
• Dinyalakan atau dimatikan: Anda menentukan apakah Webhook ini sekarang dinyalakan (Active) atau dimatikan sementara (Inactive). Jika dimatikan, tidak ada tindakan apa pun yang dijalankan meskipun hal yang ditentukan terjadi.

Ketika hal yang ditentukan benar-benar terjadi, Webhook menjalankan tindakan yang telah ditentukan. Saat mengirim ke alamat di luar, permintaan itu membawa informasi seperti apa yang terjadi dan pada produk mana hal itu terjadi. Program di luar yang menerima permintaan melihat informasi tersebut lalu mengerjakan tugasnya.

Pada perubahan apa permintaan dikirim

"Hal" yang memicu permintaan adalah perubahan yang terjadi pada sumber daya di dalam Space. Anda bisa memilih saat sesuatu terjadi pada Content seperti produk, Media yaitu berkas yang diunggah, atau Content Type yaitu kerangka formulir.

Perubahan yang bisa dipilih untuk setiap sumber daya adalah sebagai berikut.

Misalnya, "kirim permintaan setiap kali produk baru didaftarkan" berarti memilih "Create pada produk (Content)".

Pada satu Webhook, Anda juga bisa memilih beberapa perubahan sekaligus. Jika Anda memilih "saat produk didaftarkan" dan "saat produk diubah", permintaan akan terkirim ketika salah satu dari keduanya terjadi.

Mempersempit dengan syarat

Ada kalanya Anda tidak ingin selalu mengirim permintaan hanya karena perubahan yang dipilih terjadi. Misalnya, Anda mungkin ingin menerimanya "bukan untuk semua Content, melainkan hanya saat Content yang dibuat dengan formulir 'produk' didaftarkan". Dalam kasus seperti ini, Anda memasang filter untuk mempersempit kapan permintaan dikirim.

Satu filter terdiri dari satu baris "berdasarkan apa, dibandingkan dengan cara apa". Apa yang dijadikan dasar penyaringan dipilih dari empat hal.

• Item dibuat dengan formulir apa: Misalnya, permintaan dikirim hanya untuk Content yang dibuat dengan Content Type "produk". Ini syarat yang paling sering digunakan.
• Apakah satu item tertentu: Permintaan dikirim hanya untuk perubahan yang terjadi pada satu item tertentu yang ditetapkan.
• Item dibuat oleh siapa: Permintaan dikirim hanya untuk item yang dibuat oleh orang tertentu.
• Item terakhir diubah oleh siapa: Permintaan dikirim hanya untuk item yang terakhir diubah oleh orang tertentu.

Anda juga memilih cara membandingkannya. Anda bisa mempersempit dengan: hanya saat sama dengan nilai yang ditentukan, hanya saat berbeda, hanya saat termasuk salah satu dari beberapa nilai yang ditentukan, hanya saat tidak termasuk satu pun dari nilai-nilai itu, atau hanya saat cocok atau tidak cocok dengan format (pola) yang ditentukan.

Di pengaturan pemicu pada studio konten, Anda menambahkan syarat satu baris demi satu baris dengan Tambah Filter. Jika Anda memasang beberapa filter, permintaan hanya dikirim ketika semua syarat itu terpenuhi, dan jika Anda tidak memasang satu pun, permintaan dikirim setiap kali perubahan yang dipilih terjadi.

Mengirim dalam bentuk yang diinginkan program di luar

Jika tidak ditentukan secara khusus, permintaan akan membawa seluruh informasi item yang mengalami perubahan. Misalnya, ketika produk "스테인리스 텀블러 500ml" didaftarkan, isi yang dibawa dalam permintaan kira-kira berbentuk seperti ini.

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

(Pada kenyataannya informasi yang dibawa lebih banyak, dan di atas hanya sebagian yang dipilih.) Program di luar dapat memilih nilai yang dibutuhkan dari dalam ini. Namun ada juga program yang formatnya sudah ditetapkan, "saya hanya mau menerima dalam bentuk seperti ini". Dalam kasus itu, di bagian Payload pada studio konten, Anda memilih Sesuaikan Webhook payload lalu menuliskan sendiri bentuk yang akan dikirim.

Saat menuliskan bentuk yang dikirim, untuk tempat yang akan diisi dengan nilai yang ditarik dari data di atas, Anda menggunakan penanda tempat. Penanda tempat berbentuk { /payload/… }. Di sini payload menunjuk pada keseluruhan item yang ditampilkan di atas, dan jalur setelahnya menunjuk dengan tepat nilai yang diinginkan.

• { /payload/sys/id } → id di dalam sys pada data di atas (nomor unik produk)
• { /payload/fields/productName/ko-KR } → ko-KR dari productName di dalam fields (nama produk dalam bahasa Korea). Setelah fields/, Anda menambahkan ID dari Field (jika nama produk maka productName) lalu kode bahasa (jika bahasa Korea maka ko-KR) secara berurutan.

Misalnya, jika program penerjemah meminta "berikan teks yang akan diterjemahkan dan nomor produk dalam bentuk ini", Anda menuliskan payload seperti ini.

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

Maka pada saat produk tumbler didaftarkan, penanda tempat akan diganti dengan nilai sesungguhnya dan dikirim seperti ini.

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

Penanda tempat yang sama juga bisa dimasukkan ke alamat tujuan pengiriman (URL) atau ke nilai header, dan Anda juga bisa memilih cara pengiriman (method) serta format (JSON atau format formulir). Jika tidak ada nilai pada jalur yang ditunjuk, tempat itu menjadi nilai kosong.

Nilai yang tidak boleh terlihat oleh orang lain seperti kunci API eksternal saat menambahkan header sebaiknya diatur tipenya menjadi Secret. Dengan begitu nilai tersebut disimpan dalam keadaan tersamar dan tidak terlihat oleh pengguna akhir.

Menjalankan Script alih-alih URL

Sejauh ini, Webhook mengirim permintaan ke alamat di luar (URL). Sebagai gantinya, Webhook juga bisa menjalankan Script yang telah Anda buat di dalam Space. Script adalah alat yang menjalankan pekerjaan yang telah ditentukan (membuat dan mengubah sumber daya, dan sebagainya) di dalam Space tanpa perlu keluar. Anda menggunakan cara ini ketika ingin menyelesaikan pekerjaan lanjutan di dalam Space tanpa melalui program di luar.

Satu Webhook hanya melakukan tepat satu dari dua hal: mengirim ke alamat di luar atau menjalankan Script. Anda menentukannya di Target permintaan pada layar pembuatan. Jika Anda memilih Masukkan URL, permintaan dikirim ke alamat seperti sebelumnya, dan jika sebagai gantinya Anda memilih satu Script dari daftar, Script itu yang dijalankan.

Jika Anda memilih Script, akan muncul pula Run as yang menentukan atas nama identitas siapa Script itu dijalankan. Pilih salah satu dari keduanya.

• Pembuat Webhook (default): "Dibuat oleh" dari sumber daya apa pun yang dibuat atau diubah selama eksekusi tercatat sebagai orang yang membuat Webhook.
• Pengguna yang memicu: Tercatat sebagai pengguna yang memicu perubahan itu.

Pengaturan ini hanya menentukan tanda "siapa yang melakukannya" yang tertinggal pada sumber daya, dan tidak memperluas atau mempersempit apa yang bisa dilakukan Script. Cakupan hal yang bisa dilakukan Script sudah ditentukan saat Script itu dibuat.

Urutan untuk memilihnya secara langsung adalah sebagai berikut.

1. Di layar pembuatan, tekan Target permintaan.
2. Pilih Script yang akan dijalankan dari daftar. Ini berarti memilih Script alih-alih Masukkan URL.
3. Pilih identitas di Run as. Default-nya adalah Pembuat Webhook.

Apa itu Script dan bagaimana cara membuatnya dibahas di Script.

Membuat Webhook toko pakaian

Sekarang Anda akan membuat satu Webhook di Space toko pakaian. Ini Webhook yang "ketika produk baru didaftarkan, memberitahukan hal itu ke program penerjemah luar yang sudah disiapkan". Anggaplah alamat program di luar yang menerima permintaan adalah https://example.com/translate.

1. Buka layar Webhook di pengaturan Space toko pakaian.
2. Tekan tombol Buat di kanan atas.
3. Masukkan Notifikasi terjemahan produk baru pada kolom nama. Nama ini untuk mengenali nanti Webhook yang mana.
4. Tentukan perubahan yang akan mengirim permintaan. Untuk mengirim hanya pada perubahan tertentu, pilih Pilih triggering events tertentu lalu tentukan perubahan yang diinginkan (di sini Create pada produk (Content)), dan untuk mengirim pada semua perubahan, pilih Trigger untuk semua events.
5. Masukkan alamat program di luar yang menerima permintaan, https://example.com/translate, pada kolom URL.
6. Jika Anda menyalakan Aktif, permintaan langsung dikirim segera setelah dibuat (Active). Jika hanya ingin mencoba sebentar, matikan (Inactive).
7. Tekan tombol Buat untuk membuat Webhook.

Jika Notifikasi terjemahan produk baru muncul di daftar dalam status Active, berarti Webhook telah dibuat.

Setelah membuatnya, coba daftarkan satu produk baru di toko pakaian. Pada saat didaftarkan, Webhook mengirim permintaan ke alamat yang telah dituliskan. Apakah permintaan terkirim dengan baik dan bagaimana program di luar merespons dapat Anda periksa di catatan pemanggilan Webhook.

Menyalakan, mematikan, dan mengubah

Webhook dapat Anda nyalakan dan matikan kapan saja setelah dibuat. Ketika ingin menghentikan permintaan sementara, jangan dihapus, melainkan matikan menjadi Inactive. Selama dimatikan, permintaan tidak terkirim meskipun Anda mendaftarkan produk baru. Jika Anda menyalakannya kembali menjadi Active, permintaan mulai dikirim lagi sejak saat itu.

Jika Anda membuka kembali Webhook yang telah dibuat, Anda bisa mematikan atau menyalakan kembali Aktif. Isi seperti nama, alamat tujuan pengiriman, dan perubahan yang dipanggil juga bisa diubah nanti, dan Webhook yang tidak lagi digunakan dapat Anda hapus.

Hal yang dilakukan berikutnya

• Pemodelan Content: Membahas cara membuat kerangka formulir Content seperti "produk" yang menjadi sasaran permintaan Webhook.
• Menulis Content: Anda bisa mendaftarkan produk sungguhan untuk memeriksa apakah Webhook bekerja.
• Script: Membahas cara membuat pekerjaan yang berjalan di dalam Space, yang bisa dijalankan Webhook alih-alih URL.
• Referensi API: Membahas format permintaan, respons, dan spesifikasi field yang digunakan saat membuat dan mengelola Webhook langsung dari program.