Mulai

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.

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

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

Parameter	Sample Value	Description
`hub.mode`	`subscribe`	This value will always be set to `subscribe`.
`hub.challenge`	`1158201444`	An `int` you must pass back to us.
`hub.verify_token`	`meatyhamhock`	A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names.

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (e.g., the photos field on the user object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the user object's photos field and one of your app's Users posted a Photo, we would send you a POST request that would look something like this:

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"
}

Payload Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.

Property	Description	Type
`object`	The object's type (e.g., `user`, `page`, etc.)	`string`
`entry`	An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together.	`array`
`id`	The object's ID	`string`
`changed_fields`	An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`changes`	An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`time`	A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred).	`int`

Validating Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but you should.

To validate the payload:

Generate a SHA256 signature using the payload and your app's App Secret.
Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS.

Frequency

Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.

If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.

Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.

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.

mTLS untuk Webhooks

TLS bersama (mTLS) adalah metode autentikasi bersama.

mTLS memastikan bahwa para pihak di setiap ujung koneksi jaringan adalah pihak yang mereka klaim dengan memverifikasi bahwa mereka berdua memiliki kunci pribadi yang benar. Informasi dalam sertifikat TLS masing-masing menyediakan verifikasi tambahan.

Cara mengonfigurasi mTLS

Setelah mengaktifkan mTLS pada langganan Akun WhatsApp Business Anda, Meta akan menampilkan sertifikat klien bersama dengan sertifikat perantara penandatanganannya. Kedua sertifikat digunakan untuk membuat Jabat tangan TLS permintaan Webhook ke server Anda. Server Anda kemudian dapat memverifikasi identitas pengirim permintaan ini melalui rantai kepercayaan dan nama umum (CN).

Sertifikat klien ditandatangani oleh sertifikat CA perantara, DigiCert SHA2 High Assurance Server CA, dan kemudian oleh sertifikat root CA, DigiCert High Assurance EV Root CA. Perhatikan bahwa sertifikat perantara juga menandatangani sertifikat untuk graph.facebook.com:

Verifikasi Sertifikat Klien

Setelah menyiapkan HTTPS untuk menerima permintaan Webhook, selesaikan langkah-langkah berikut untuk memverifikasi sertifikat klien dan nama umumnya client.webhooks.fbclientcerts.com:

Instal sertifikat root
Verifikasi sertifikat klien terhadap sertifikat root
Verifikasi nama umum (client.webhooks.fbclientcerts.com) dari sertifikat klien

Catatan: Server yang menerima Webhooks harus menggunakan HTTPS; dan kami selalu memverifikasi sertifikat dari server HTTPS Anda demi keamanan.

Contoh

Bergantung pada penyiapan server Anda, langkah-langkah di atas memiliki detail yang berbeda-beda. Kami ilustrasikan dengan dua contoh, satu untuk Nginx dan satu untuk Penyeimbang Beban Aplikasi (ALB) AWS.

Nginx

Unduh sertifikat root (DigiCert High Assurance EV Root CA) dari DigiCert ke server Anda, contohnya /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem

Aktifkan mTLS dengan arahan Nginx (contoh cuplikan layar)

ssl_verify_client       on;
ssl_client_certificate  /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem;
ssl_verify_depth        3;

Verifikasi CN dari variabel tersemat Nginx $ssl_client_s_dn sama dengan "client.webhooks.fbclientcerts.com" (contoh cuplikan layar)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

Penyeimbang Muatan Aplikasi (ALB) AWS

Unduh sertifikat perantara (DigiCert SHA2 High Assurance Server CA) dari DigiCert ke bucket S3. Sertifikat root tidak diterima oleh AWS karena ditandatangani menggunakan algoritma SHA1withRSA; sedangkan sertifikat perantara ditandatangani menggunakan SHA256withRSA sehingga diterima.
Konfigurasikan pendengar HTTPS di ALB untuk mengaktifkan mTLS dengan penyimpanan tepercaya yang berisi sertifikat di bucket S3 (contoh cuplikan layar).
Dalam kode aplikasi Anda, ekstrak CN dari header HTTP “X-Amzn-Mtls-Clientcert-Subject”, dan verifikasikan sama dengan “client.webhooks.fbclientcerts.com”.

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: