Memulai

Dokumen ini akan menjelaskan cara menyiapkan Webhook yang akan memberi tahu Anda setiap kali Pengguna aplikasi Anda menerbitkan perubahan terhadap Foto Pengguna. Setelah Anda memahami cara menyiapkan Webhook ini, Anda akan tahu cara menyiapkan semua Webhooks.

Menyiapkan Webhook mewajibkan Anda untuk:

Membuat endpoint di server aman yang dapat memproses permintaan HTTP.
Mengonfigurasi produk Webhooks di Dasbor Aplikasi pada aplikasi.

Langkah-langkah ini dijelaskan secara mendetail di bawah.

Membuat Endpoint

Endpoint harus dapat memproses dua jenis permintaan HTTPS: Permintaan Verifikasi dan Notifikasi Peristiwa. Karena kedua permintaan ini menggunakan HTTP, server harus memiliki TLS yang valid atau sertifikat SSL yang secara tepat dikonfigurasi dan diinstal. Sertifikat yang ditandatangani sendiri tidak didukung.

Bagian di bawah menjelaskan akan seperti apa di tiap permintaan dan cara menanggapinya. Alternatifnya, Anda bisa menggunakan aplikasi contoh kami yang sudah dikonfigurasi untuk memproses permintaan ini.

Permintaan Verifikasi

Saat Anda mengonfigurasi produk Webhooks di Dasbor Aplikasi di aplikasi Anda, kami akan mengirimkan permintaan GET ke URL endpoint Anda. Verifikasi permintaan akan menyertakan parameter string kueri berikut, yang ditambahkan ke akhir URL endpoint Anda. Hasilnya akan seperti ini:

Permintaan Verifikasi Contoh

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

Parameter	Nilai Contoh	Deskripsi
`hub.mode`	`subscribe`	Nilai ini akan selalu diatur ke `subscribe`.
`hub.challenge`	`1158201444`	`int` Anda harus meneruskan kembali kepada kami.
`hub.verify_token`	`meatyhamhock`	String yang kami dapatkan dari kolom Verifikasikan Token di Dasbor Aplikasi pada aplikasi. Anda akan mengatur string ini setelah Anda menyelesaikan langkah pengaturan konfigurasi Webhooks.

Catatan:PHP mengonversi titik (.) menjadi garis bawah (_) dalam nama parameter.

Memvalidasi Permintaan Verifikasi

Saat endpoint menerima permintaan verifikasi, yang harus Anda lakukan:

Verifikasikan bahwa nilai hub.verify_token cocok dengan string yang Anda atur Verifikasikan Token saat Anda mengonfigurasi produk Webhooks di Dasbor Aplikasi (Anda belum menyiapkan string token ini).
Tanggapi dengan nilai hub.challenge.

Jika Anda membuka Dasbor Aplikasi dan mengonfigurasi produk Webhooks (dengan demikian memicu Permintaan Verifikasi), dasbor akan menunjukkan apakah endpoint memvalidasi permintaan dengan benar. Jika Anda menggunakan endpoint /app/subscriptions Graph API untuk mengonfigurasi produk Webhooks, API akan menunjukkan keberhasilan atau kegagalan dengan tanggapan.

Notifikasi Peristiwa

Saat Anda mengonfigurasi produk Webhooks, Anda akan berlangganan ke fields spesifik pada jenis object (mis., kolom photos pada objek user). Saat ada perubahan ke salah satu kolom ini, kami akan mengirimkan endpoint Anda permintaan POST dengan muatan JSON yang menjelaskan perubahan tersebut.

Sebagai contoh, jika Anda berlangganan kolom user objek photos dan salah satu Pengguna aplikasi Anda memposting Foto, kami akan mengirimi Anda permintaan POST yang akan terlihat seperti ini:

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

Konten Payload

Payload akan berisi objek yang menjelaskan perubahan. Saat mengonfigurasi produk Webhooks, Anda dapat menandakan apakah payload harus hanya berisi nama kolom yang diubah, atau juga harus menyertakan nilai baru.

Kami memformat semua payload dengan JSON, sehingga Anda dapat mem-parse payload menggunakan metode atau paket parsing JSON umum.

Kami tidak menyimpan data notifikasi peristiwa Webhook yang kami kirimkan kepada Anda, jadi pastikan Anda merekam dan menyimpan konten muatan yang ingin Anda pertahankan.

Sebagian besar muatan akan berisi properti umum berikut, tetapi konten dan struktur tiap muatan berbeda-beda, bergantung pada kolom objek yang Anda ikuti. Lihat dokumen referensi untuk melihat kolom mana yang akan disertakan.

Properti	Deskripsi	Jenis
`object`	Jenis objek (mis., `user`, `page`, dsb.)	`string`
`entry`	Array yang berisi objek yang menggambarkan perubahan. Beberapa perubahan dari objek berbeda dengan jenis yang sama mungkin akan dikelompokkan bersama.	`array`
`id`	ID objek	`string`
`changed_fields`	Array string yang menunjukkan nama-nama kolom yang sudah diganti. Hanya disertakan jika Anda menonaktifkan pengaturan Sertakan Nilai saat mengonfigurasi produk Webhooks di Dasbor Aplikasi pada aplikasi Anda.	`array`
`changes`	Array yang berisi objek yang menggambarkan perubahan kolom dan nilai barunya. Hanya disertakan jika Anda mengaktifkan pengaturan Sertakan Nilai saat mengonfigurasi produk Webhooks di Dasbor Aplikasi pada aplikasi Anda.	`array`
`time`	Cap waktu UNIX yang mengindikasikan saat Notifikasi Peristiwa dikirim (bukan saat perubahan yang memicu terjadinya notifikasi).	`int`

Memvalidasi Muatan

Kami menandai semua muatan Notifikasi Peristiwa dengan tanda tangan SHA256 dan menyertakan tanda tangan tersebut dengan header X-Hub-Signature-256, diawali dengan sha256=. Anda tidak harus memvalidasi muatan tersebut, tetapi sangat disarankan.

Untuk memvalidasi payload:

Buat tanda tangan SHA256 menggunakan muatan dan Rahasia Aplikasi aplikasi Anda.
Bandingkan tanda tangan tersebut dengan tanda tangan di header X-Hub-Signature-256 (apa pun setelah sha256=). Jika tanda tangannya cocok, berarti payload tersebut asli.

Menanggapi Notifikasi Peristiwa

Endpoint Anda harus menanggapi semua Notifikasi Peristiwa dengan 200 OK HTTPS.

Frekuensi

Pemberitahuan peristiwa diagregasikan dan dikirimkan dalam batch dengan maksimal 1000 pembaruan. Namun, sistem batch tidak dapat dijamin, jadi pastikan untuk menyesuaikan server Anda untuk menangani tiap Webhook satu per satu.

Jika pembaruan yang dikirimkan ke server Anda gagal, kami akan segera mencoba kembali, lalu mencoba beberapa kali dengan menurunkan frekuensi selama 36 jam berikutnya. Server Anda harus menangani deduplikasi dalam kasus ini. Tanggapan yang tidak diterima dalam 36 jam akan dibatalkan.

Catatan: Frekuensi yang dikirimkan notifikasi peristiwa Messenger berbeda. Lihat dokumentasi Webhooks Platform Messenger untuk informasi selengkapnya.

Mengonfigurasi Produk Webhooks

Setelah endpoint atau aplikasi contoh siap, gunakan Dasbor Aplikasi pada aplikasi untuk menambahkan atau mengonfigurasi produk Webhooks. Anda juga dapat melakukan ini secara terprogram menggunakan endpoint /{app-id}/subscriptions untuk semua Webhooks kecuali Instagram.

Dalam contoh ini, kami akan menggunakan dasbor untuk mengonfigurasi Webhook yang mengikuti perubahan pada foto Pengguna aplikasi.

Di Dasbor Aplikasi, buka Produk > Webhooks, pilih Pengguna dari menu pilihan, lalu klik Berlangganan objek ini.
Memilih objek Pengguna.
Masukkan URL endpoint Anda di kolom URL Panggilan Balik dan masukkan string di kolom Verifikasikan Token. Kami akan menyertakan string ini di semua Permintaan Verifikasi. Jika Anda menggunakan salah satu aplikasi contoh kami, ini harus berupa string sama yang Anda gunakan untuk variabel konfigurasi TOKEN Anda.
Jika Anda ingin muatan notifikasi peristiwa menyertakan nama kolom yang telah berubah beserta nilai barunya, atur tombol Sertakan Nilai ke Ya.
Memasukkan URL endpoint dan string token verifikasi.
Setelah Anda mengeklik Verifikasi dan Simpan, kami akan mengirim Permintaan Verifikasi ke endpoint Anda yang harus Anda validasi. Jika endpoint berhasil memvalidasi permintaan tersebut, Anda akan melihat ini:
Validasi berhasil.
Langkah terakhir adalah berlangganan setiap kolom. Segera berlangganan kolom photos dan kirimkan Notifikasi Peristiwa.
Berlangganan kolom Foto di objek Pengguna.
Jika dikonfigurasi secara tepat, endpoint akan memvalidasi payload dan mengeksekusi kode apa pun yang sudah Anda siapkan saat validasi berhasil. Jika Anda menggunakan aplikasi contoh kami, muat URL aplikasi di browser web. Konten muatan akan ditampilkan:
Aplikasi Contoh yang menampilkan muatan notifikasi.

Langkah Berikutnya

Setelah mengetahui cara menyiapkan Webhooks, Anda dapat melihat dokumen tambahan kami yang menjelaskan langkah-langkah tambahan yang diperlukan saat menyiapkan Webhooks untuk produk tertentu: