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 mengirim permintaan ke tempat yang sudah 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. Anda juga akan mempelajari WriteBack, yang mengisi kembali hasil yang dikembalikan program di luar ke produk.

Apa yang dilakukan Webhook

Webhook terdiri dari tiga hal yang ditentukan terlebih dahulu.

• Kapan dikirim: Anda menentukan saat hal apa permintaan dikirim. Misalnya bisa ditetapkan "ketika produk (Content) baru didaftarkan".
• Ke mana dikirim: Anda menentukan alamat program di luar yang akan menerima permintaan. Anda menuliskan satu alamat internet (URL).
• Dinyalakan atau dimatikan: Anda menentukan apakah Webhook ini sekarang dinyalakan (ACTIVE) atau dimatikan sementara (INACTIVE). Jika dimatikan, permintaan tidak dikirim meskipun hal yang ditentukan terjadi.

Ketika hal yang ditentukan benar-benar terjadi, Webhook mengirim permintaan untuk memberitahukan hal itu ke alamat yang telah dituliskan. 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 trigger 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 tumbler 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 tinggal 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.

Mengisi kembali dengan respons yang diterima: WriteBack

Jika bagian sebelumnya menentukan bentuk permintaan yang dikirim, WriteBack menangani respons yang dikembalikan. Ketika Webhook memanggil program di luar dan menerima respons normal (2xx), ia dapat mengolah respons itu untuk membuat, mengubah, atau menerbitkan dan menghapus Content maupun Media di dalam Space. Proses menyalin dan menempelkan hasil oleh orang menjadi hilang.

Mari ikuti contoh penerjemahan toko pakaian sampai akhir. Sebelumnya Anda mengirim nama produk berbahasa Korea dari produk baru ke program penerjemah. Anggaplah program penerjemah merespons seperti ini.

{ "translated": "Stainless Tumbler 500ml" }

Anda menyusun WriteBack yang mengisi teks terjemahan ini ke kolom nama produk berbahasa Inggris pada produk yang sama. Di bagian WriteBack pada studio konten, Anda menambahkan satu aksi Update (ubah) untuk Content dengan + Tambah Operasi lalu mengaturnya seperti ini.

• Target: Jika tidak ditentukan secara khusus, produk yang mengalami perubahan itu (tumbler) menjadi target.
• Kolom dan bahasa yang diisi: Karena ini nama produk berbahasa Inggris, kolomnya adalah nama produk (productName) dan bahasanya adalah bahasa Inggris (en-US).
• Nilai yang dimasukkan: { /response/translated } yang menunjuk teks terjemahan pada respons.

Maka kolom nama produk berbahasa Inggris pada produk tumbler terisi dengan Stainless Tumbler 500ml.

WriteBack seperti ini sangat berguna untuk dihubungkan dengan LLM eksternal. Misalnya, Anda bisa menyusun alur dalam satu Webhook untuk menyimpan gambar promosi yang dibuat dari deskripsi produk sebagai Media, atau membuat Content baru dari kalimat perkenalan yang dihasilkan.

Urutan kerja

1. Ketika perubahan terjadi, Webhook mengirim permintaan ke program di luar dalam bentuk yang telah ditentukan.
2. Jika respons adalah 2xx, aksi (operasi) WriteBack yang telah ditambahkan dijalankan berurutan dari atas.
3. Setiap aksi saling independen, jadi meskipun salah satu gagal, sisanya tetap dijalankan.
4. Pembuatan, perubahan, penghapusan, dan penerbitan yang muncul dari WriteBack juga ditangkap kembali sebagai perubahan, sehingga dapat memanggil Webhook lain yang berlangganan perubahan itu secara beruntun. Putaran tak berujung yang berulang otomatis diperiksa dan dicegah saat Webhook dibuat atau diubah.

Pembuat (createdBy) dari sumber daya yang dibuat atau diubah oleh WriteBack menjadi pengguna yang memicu perubahan itu.

Ekspresi nilai

Nilai yang diisi diambil dengan penanda tempat ({ /… }) yang sama seperti yang dilihat sebelumnya. Namun, pada WriteBack ada dua akar yang bisa ditunjuk.

• Jika Anda menggunakan satu penanda tempat secara tunggal ({ /response/url }), ia mengambil bentuk asli nilai itu (teks, angka, kumpulan) apa adanya.
• Jika Anda mencampurnya dengan teks ("Dibuat: { /payload/sys/id }"), semuanya disambung menjadi satu teks.
• Ketika respons datang sebagai teks apa adanya, bukan JSON, gunakan { /response } untuk menerima seluruh respons sebagai teks (jalur turunan di dalamnya tidak bisa ditunjuk).

Menangani Content ($content)

Ini aksi yang membuat atau mengubah Content dengan respons. Item yang ditentukan adalah sebagai berikut.

Menangani Media ($media)

Ini aksi yang memasukkan berkas yang diterima dari respons sebagai Media atau mengubah status Media.

$media juga bisa digunakan sebagai nilai kolom pada Content. Setelah memasukkan berkas yang diterima dari respons sebagai Media, Anda bisa langsung menghubungkan Media itu ke kolom, sehingga "Content yang berisi gambar" dibuat sekaligus.

Delete , Archive , Unarchive pada Media tidak hanya menangani informasi di daftar, tetapi juga berkas sesungguhnya yang ada di penyimpanan.

Cara mengatur dan contohnya

Di bagian WriteBack pada studio konten, Anda menambahkan aksi satu per satu dengan + Tambah Operasi. Anda bisa berpindah antara cara Visual yang mengisi item di layar, dan cara JSON yang menuliskan langsung kumpulan writeBacks seperti di bawah. Dengan cara mana pun hasilnya sama.

Membuat produk baru dengan menempelkan gambar yang dibuat LLM eksternal. Anda memasukkan alamat gambar yang dibawa dalam respons sebagai Media, lalu membuat Content baru yang memiliki gambar itu.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Produk Content Type sys.id>" } },
        "fields": {
          "productName": "{ /payload/fields/productName/ko-KR }",
          "photo": { "$media": { "source": "{ /response/data/0/url }", "encoding": "Url" } }
        }
      }
    }
  ]
}

Memperkaya produk yang mengalami perubahan. Jika target dilewati, Content yang mengalami perubahan menjadi target. Nilai dari respons diisi ke kolom produk itu.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Update",
        "locale": "en-US",
        "fields": { "productName": "{ /response/translated }" }
      }
    }
  ]
}

Membuatnya hanya sebagai Draft untuk diterbitkan setelah ditinjau. Jika publish dimatikan, item tidak diterbitkan dan dibiarkan sebagai draf, sehingga bisa diterbitkan setelah orang memeriksanya.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Content Type sys.id>" } },
        "fields": { "text": "{ /response/choices/0/message/content }" },
        "publish": false
      }
    }
  ]
}

Memasukkan gambar respons sebagai Media yang berdiri sendiri. Jika menerima lewat alamat, atur encoding ke Url, dan jika menerima sebagai data berkas yang dibawa dalam respons, atur ke Base64.

{
  "writeBacks": [
    { "$media": { "action": "Create", "source": "{ /response/data/0/url }", "encoding": "Url" } }
  ]
}

Delete , Publish , Unpublish , Archive , Unarchive bentuknya sama. Jika Anda hanya menuliskan action dan target yang akan diubah, hanya status target itu yang berubah (jika target dilewati, item yang mengalami perubahan). Misalnya, untuk menerbitkan Content yang ditunjukkan respons, Anda menuliskannya seperti ini.

{
  "writeBacks": [
    { "$content": { "action": "Publish", "target": "{ /response/contentId }" } }
  ]
}

Jika Anda menambahkan beberapa aksi, semuanya dijalankan sesuai urutan penulisan. Caranya seperti menempatkannya berurutan, misalnya "mengisi hasil terjemahan ke produk, lalu memasukkan gambar promosi sebagai Media".

Memeriksa hasil eksekusi

Bagaimana hasil setiap aksi WriteBack dapat Anda periksa di catatan pemanggilan Webhook. Setiap aksi meninggalkan hal berikut.

Untuk aksi yang berhasil, Anda bisa menelusuri sumber daya apa yang dibuat atau diubah melalui ID hasil. Jika respons bukan 2xx, WriteBack sama sekali tidak dijalankan sehingga catatan hasil pun kosong.

Hal yang perlu diketahui

• Hanya satu perubahan yang mengirim permintaan. Jika satu Webhook menangkap "pendaftaran (Create)" dan "penerbitan (Publish)" sekaligus, program di luar bisa dipanggil dua kali. Untuk Webhook yang menggunakan WriteBack, pilihlah hanya satu perubahan.
• Hanya memindahkan nilai, tidak bisa menghitung. Ia hanya mengeluarkan nilai dari respons dan memasukkannya, tidak melakukan pemrosesan seperti percabangan syarat atau perulangan.
• Tidak mencoba ulang. Jika terjadi masalah di tengah pemrosesan, aksi itu bisa langsung hilang.
• Cegah pembuatan yang sembarangan. Content Type yang hanya dibuat lewat WriteBack sebaiknya dipersempit izinnya agar pengguna biasa tidak bisa membuatnya langsung.

Membuat Webhook toko pakaian

Sekarang mari 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 saja (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 tinggal dihapus.

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.
• Referensi API: Membahas format permintaan, respons, dan spesifikasi field yang digunakan saat membuat dan mengelola Webhook langsung dari program.