Webhooks

Ringkasan

Webhooks memungkinkan aplikasi integrasi khusus untuk berlangganan peristiwa di Workplace dan menerima info terkini secara realtime. Saat terjadi perubahan di Workplace, permintaan HTTPS POST dikirim ke URL panggilan balik untuk setiap aplikasi integrasi khusus yang berlangganan topik Webhooks yang relevan.

Hal ini membuat aplikasi lebih efisien, karena aplikasi akan mengetahui kapan tepatnya perubahan terjadi dan tidak perlu bergantung pada permintaan Graph API yang berkelanjutan atau bahkan berkala untuk mendapatkan konten terbaru.

Dukungan Webhooks untuk Workplace disediakan oleh kerangka kerja yang sama yang mempersembahkan Webhooks untuk Graph API.

Berlangganan Topik Webhooks

Dialog Edit Integrasi Khusus menyediakan tab untuk setiap topik Webhooks yang tersedia untuk aplikasi di Workplace.

Bagian Webhooks dalam dialog Edit Integrasi Khusus

Untuk menambahkan langganan Webhooks baru tentang topik tertentu, sediakan URL panggilan balik dan token verifikasi, lalu pilih kolom langganan yang Anda perlukan untuk fungsi yang akan disediakan oleh aplikasi Anda.

Anda hanya dapat berlangganan satu URL per topik Webhooks, tetapi Anda dapat menggunakan URL yang sama untuk beberapa topik.

Menangani Permintaan Verifikasi

Saat Anda menambahkan langganan baru, atau mengubah langganan yang sudah ada, server Meta akan membuat permintaan GET ke URL panggilan balik untuk memverifikasi validitas server panggilan balik.

String kueri akan ditambahkan ke URL ini dengan parameter berikut:

hub.mode - String "subscribe" diteruskan di parameter ini
hub.challenge - String acak
hub.verify_token - Nilai verify_token Anda tentukan saat membuat langganan

Saat endpoint menerima permintaan verifikasi, yang harus Anda lakukan:

Verifikasikan bahwa nilai hub.verify_token sesuai dengan string yang Anda atur di kolom Verifikasikan Token saat Anda mengonfigurasi Webhooks.
Tanggapi dengan nilai hub.challenge.

Keamanan Webhooks

Semua panggilan Webhooks ke URL panggilan balik yang ditentukan developer dilakukan melalui HTTPS, memastikan keamanan tingkat transportasi untuk muatan Webhooks.

Untuk memberikan keamanan tambahan, header HTTPX-Hub-Signature-256 disertakan dalam setiap muatan POST, yang harus digunakan untuk memverifikasi bahwa muatan berasal dari server Meta.

Untuk detail lengkap tentang perilaku ini, buka dokumentasi Kerangka Kerja Webhooks.

Semua panggilan Webhooks ke URL panggilan balik yang ditentukan developer dilakukan melalui HTTPS, memastikan keamanan tingkat transportasi untuk muatan Webhooks.

Berlangganan Webhooks menggunakan panggilan API

Panggilan API untuk membaca atau mengubah langganan Webhooks harus dibuat menggunakan token aplikasi dan bukan token integrasi khusus yang biasanya. Token aplikasi dapat dibuat dengan menggabungkan ID aplikasi, simbol '|', dan rahasia aplikasi.

Contoh:

Data	String
ID Aplikasi	504221332732118
Rahasia aplikasi	d76ab3f35f3ff5aa6ffdc8637a660d2ea7
Token aplikasi:	504221332732118\|d76ab3f35f3ff5aa6ffdc8637a660d2ea7

Mendapatkan langganan Webhooks saat ini (menggunakan token aplikasi)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Menambahkan langganan Webhooks baru (menggunakan token aplikasi)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Memecahkan Masalah Langganan Halaman/Aplikasi

Jika Webhooks tidak diterima seperti yang diharapkan, direkomendasikan untuk memeriksa apakah langganan antara halaman dan aplikasi telah disiapkan dengan benar. Ini seharusnya disiapkan secara otomatis, tetapi dalam beberapa kasus, penyiapan dapat gagal. Contoh: jika penyampaian Webhooks gagal dalam periode yang panjang, langganan ini bisa dihapus. Untuk aplikasi pihak ketiga, ini akan menghasilkan pemberitahuan di dasbor aplikasi.

Untuk memeriksa langganan ini, panggilan API berikut tersedia:

Mendapatkan langganan aplikasi/halaman saat ini (menggunakan token halaman)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Untuk membuat ulang langganan ini, panggilan API berikut tersedia:

Membuat ulang langganan aplikasi/halaman saat ini (menggunakan token halaman)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Topik Webhooks

Aktivitas di Workplace dikelompokkan ke dalam topik-topik. Setiap topik memiliki sejumlah kolom yang dipetakan ke peristiwa pada topik tertentu. Aplikasi dapat berlangganan pembaruan Webhooks pada setiap topik, dan untuk kolom tertentu dalam setiap topik.

Workplace saat ini menyediakan Webhooks untuk topik dan grup berikut:

Halaman

Informasi selengkapnya tersedia di Dokumen Referensi Topik Halaman.

Kolom Langganan	Perilaku
`mention`	Terpicu saat halaman integrasi khusus (bot) disebutkan dalam grup.
`messages`	Terpicu saat halaman integrasi khusus (bot) dikirimi pesan di Obrolan Workplace.
`message_deliveries`	Terpicu saat pesan yang dikirim oleh halaman integrasi khusus (bot) disampaikan.
`messaging_postbacks`	Terpicu saat tombol postback ditekan di Obrolan Workplace.
`message_reads`	Terpicu saat pesan dari halaman integrasi khusus (bot) dibaca oleh penerima.

Grup

Informasi selengkapnya tersedia di Dokumen Referensi Topik Grup.

Kolom Langganan	Perilaku
`posts`	Terpicu saat postingan ditambahkan, diperbarui, atau dihapus dalam grup.
`comments`	Terpicu setiap kali komentar baru ditambahkan, diperbarui, atau dihapus pada postingan grup.
`membership`	Terpicu saat keanggotaan grup berubah.
`membership_requests`	Dipicu ketika pengguna meminta keanggotaan grup.

Pengguna

Informasi selengkapnya tersedia di Dokumen Referensi Topik Anggota.

Kolom Langganan	Perilaku
`status`	Terpicu saat seorang pengguna memposting atau mengedit pembaruan status di profilnya sendiri. Ini mencakup postingan di linimasa pengguna.
`events`	Terpicu setiap kali seorang pengguna membuat, menerima, atau menolak peristiwa.
`message_sends`	Terpicu setiap kali seorang pengguna mengirimkan pesan Obrolan Workplace.
`message_unsends`	Dipicu setiap kali pengguna menghapus pesan Obrolan Workplace untuk semua orang dalam sebuah utas.
`timeline_comments`	Dipicu setiap kali ada komentar pada postingan di linimasa pengguna.

Keamanan

Informasi selengkapnya tersedia di Dokumen Referensi Topik Keamanan.

`admin_activity`

Peristiwa terpicu saat admin ditambahkan atau dihapus dari komunitas Workplace

Peristiwa	Perilaku
`admin_set_to_unclaimed`	Seorang admin telah mengatur status akun pengguna ke belum diklaim dari panel admin atau melalui API Pengelolaan Akun.
`admin_force_log_out`	Seorang admin telah memaksa pengguna untuk keluar di semua perangkat dari Panel Admin.
`admin_deactivate`	Seorang admin telah menonaktifkan akun dari Panel Admin atau melalui API Pengelolaan Akun.
`admin_activate_account`	Seorang admin telah mengaktifkan akun dari Panel Admin atau melalui API Pengelolaan Akun.
`force_password_reset`	Seorang admin telah memaksa pengguna untuk mereset kata sandi dari Panel Admin.
`admin_create_account`	Seorang admin telah membuat akun dari Panel Admin.

`compromised_credentials`

Peristiwa terpicu ketika kami menduga bahwa kata sandi Workplace dari beberapa akun pengguna di sebuah komunitas mungkin berisiko bocor.

Peristiwa	Perilaku
`found_compromised_credentials`	Workplace telah menemukan kredensial tersusupi.

`files`

Peristiwa terpicu setelah aktivitas file Workplace.

Peristiwa	Perilaku
`group_file_upload`	Pengguna telah mengunggah file ke grup.
`group_file_download`	Pengguna telah mengunduh file dari grup.
`file_upload_malware_found`	File yang diunggah ditemukan berisi malware.

`groups`

Peristiwa terpicu saat seseorang membuat atau bergabung dengan Grup Multi-Perusahaan Workplace.

Peristiwa	Perilaku
`mcg_join`	Pengguna di komunitas telah bergabung dengan MCG.
`mcg_create`	Pengguna di komunitas telah membuat MCG.

`integrations`

Peristiwa terpicu saat admin membuat atau mengubah properti integrasi.

Peristiwa	Perilaku
`custom_integration_create`	Admin telah membuat integrasi khusus.
`custom_integration_edit`	Admin telah mengedit integrasi khusus.
`custom_integration_delete`	Admin telah menghapus integrasi khusus.
`custom_integration_token_reset`	Admin telah membuat token akses baru untuk integrasi khusus.
`content_app_install`	Pengguna telah membuat integrasi konten.
`content_app_uninstall`	Pengguna telah menghapus penginstalan integrasi konten.

`invites`

Peristiwa terpicu saat seseorang bergabung dengan Workplace melalui undangan mandiri.

Peristiwa	Perilaku
`coworker_invite_sent`	Pengguna telah mengundang rekan kerja untuk bergabung dengan komunitas.
`self_invite_sent`	Pengguna telah meminta email undangan untuk diri sendiri.

`passwords`

Peristiwa terpicu saat seseorang mengubah kata sandinya atau meminta reset kata sandi.

Peristiwa	Perilaku
`password_change`	Kata sandi pengguna telah diubah, sebagai hasil dari menyelesaikan pemulihan kata sandi atau melalui pengaturan akun.
`password_reset_request`	Alur pemulihan sandi pengguna telah dimulai, dan kode telah dikirim ke alamat email pengguna.
`password_reset_wrong_code`	Pengguna salah memasukkan kode pemulihan reset kata sandi.
`password_reset_success`	Alur pemulihan kata sandi pengguna telah berhasil diselesaikan.

`sessions`

Peristiwa terpicu ketika seseorang login atau keluar dari Workplace.

Peristiwa Perilaku

Peristiwa	Perilaku
`log_in`	Pengguna telah login ke Workplace dengan kata sandi atau SSO, di www atau aplikasi seluler.
`log_out`	Pengguna telah keluar dari Workplace dengan kata sandi atau SSO, di www atau aplikasi seluler. Tidak termasuk dipaksa keluar yang diinisiasi oleh admin (Lihat `admin_force_log_out`)

log_in

Pengguna telah login ke Workplace dengan kata sandi atau SSO, di www atau aplikasi seluler.

log_out

Pengguna telah keluar dari Workplace dengan kata sandi atau SSO, di www atau aplikasi seluler.

Tidak termasuk dipaksa keluar yang diinisiasi oleh admin (Lihat admin_force_log_out)

`two_factor`

Peristiwa terpicu ketika seseorang mengaktifkan atau menonaktifkan autentikasi dua faktor.

Peristiwa	Perilaku
`two_factor_enable`	Pengguna telah mengaktifkan autentikasi dua faktor dari tab Pengaturan. Ini tidak menangkap ketika seseorang mengonfirmasi ponsel tertentu, tetapi menunjukkan bahwa fitur itu diaktifkan.
`two_factor_disable`	Seorang pengguna telah menonaktifkan autentikasi dua faktor dari tab Pengaturan. Ini tidak menangkap ketika seseorang menonaktifkan autentikasi dua faktor untuk ponsel tertentu, tetapi menunjukkan bahwa fitur itu dinonaktifkan.
`add_two_factor_phone`	Pengguna telah menambahkan dan mengonfirmasi ponsel yang digunakan untuk autentikasi dua faktor.
`two_factor_code_success`	Pengguna telah memasukkan kode dua faktor yang valid saat masuk ke situs web atau situs web seluler Workplace
`two_factor_code_failure`	Pengguna telah memasukkan kode dua faktor yang tidak valid saat masuk ke situs web atau situs web seluler Workplace
`two_factor_code_success_m`	Pengguna telah memasukkan kode dua faktor yang valid saat masuk ke aplikasi seluler iOS atau Android
`two_factor_code_failure_m`	Pengguna telah memasukkan kode dua faktor yang tidak valid saat masuk ke aplikasi seluler iOS atau Android

`reseller_events`

Peristiwa terkait reseller.

Peristiwa	Perilaku
`reseller_user_added`	Mengizinkan pengguna non-admin di perusahaan reseller untuk melihat konsol reseller.
`reseller_user_removed`	Tidak mengizinkan pengguna non-admin di perusahaan reseller untuk melihat konsol reseller.
`reseller_invite_sent`	Reseller mengundang perusahaan lain untuk ditautkan dengan reseller itu.
`reseller_invite_accepted`	Perusahaan menerima undangan reseller untuk ditautkan.
`reseller_invite_declined`	Perusahaan menolak undangan reseller untuk ditautkan.

Tautan

Informasi selengkapnya tersedia di Dokumen Referensi Topik Tautan

Peristiwa	Perilaku
`preview`	Metadata tentang pengguna yang meminta akses ke tautan yang dapat dibagikan.
`collection`	Metadata untuk tautan yang dibagikan di Workplace untuk membuat pratinjau.

Galeri Pengetahuan

Informasi selengkapnya tersedia di Dokumen Graph API Kategori Galeri.

Kolom Langganan	Perilaku
`categories`	Terpicu saat konten Galeri Pengetahuan ditambahkan, diperbarui, atau dihapus, atau ketika pemirsa baca diperbarui.
`comments`	Terpicu setiap kali komentar baru ditambahkan, diperbarui, atau dihapus di Galeri Pengetahuan.
`quicklinks`	Terpicu saat tautan cepat Galeri Pengetahuan sedang ditambahkan, diperbarui, atau dihapus.