Начало работы

В этом документе рассказывается, как настроить Webhooks, который будет уведомлять вас о том, что пользователи приложения опубликовали изменения в своих фото. Поняв, как настроить этот Webhooks, вы сможете настроить любой.

Для настройки Webhooks необходимо:

Создать на защищенном сервере конечную точку, которая может обрабатывать HTTPS-запросы.
Настроить продукт Webhooks на панели вашего приложения.

Более подробно эти действия описаны ниже.

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.

Настройка продукта Webhooks

Когда ваша конечная точка или пример приложения будут готовы, добавьте и настройте продукт Webhooks с помощью панели приложений. Это также можно сделать программным путем, используя конечную точку /{app-id}/subscriptions для всех Webhooks, кроме Instagram.

В этом примере с помощью панели мы настроим Webhooks, который подписан на все изменения, вносимые в фото пользователей приложения.

На панели приложений выберите Продукты > Webhooks, выберите в меню пункт Пользователь и нажмите кнопку Подписаться на этот объект.
Выбор объекта "Пользователь"
Введите URL конечной точки в поле URL обратного вызова и строку в поле Подтвердить маркер. Мы будем добавлять эту строку во все запросы подтверждения. Если вы используете один из наших примеров приложений, она должна совпадать со строкой, которую вы использовали в переменной TOKEN вашего приложения.
Чтобы в полезные данные уведомлений о событиях добавлялись названия измененных полей и их новые значения, установите переключатель Включить ценность в положение Да.
Ввод URL конечной точки и маркера подтверждения
После того как вы нажмете кнопку Подтвердить и сохранить, мы отправим на вашу конечную точку запрос, который нужно будет подтвердить. Если ваша конечная точка подтвердит запрос, вы увидите следующее:
Успешное подтверждение.
Чтобы завершить процедуру, вам нужно подписаться на отдельные поля. Подпишитесь на поле photos и отправьте тестовое уведомление о событии.
Подписка на поле photos объекта "Пользователь".
Если конечная точка настроена правильно, она должна подтвердить полезные данные и выполнить заданный код. Если вы используете наш пример приложения, загрузите URL приложения в браузере. Должны отобразиться полезные данные:
Пример приложения с полезными данными тестового уведомления.

Аутентификация mTLS для Webhooks

Mutual TLS (mTLS) — это способ взаимной аутентификации.

mTLS подтверждает, что стороны на каждом конце сетевого соединения являются теми, за кого себя выдают, проверяя, что у обеих сторон имеется правильный закрытый ключ. Информация, содержащаяся в соответствующих сертификатах TLS, обеспечивает дополнительную проверку.

Настройка mTLS

Когда вы включите аутентификацию mTLS в подписке на аккаунт WhatsApp Business, Meta представит клиентский сертификат и его промежуточный сертификат подписи. Оба сертификата используются для подтверждения приема и передачи через TLS запросов Webhooks к вашему серверу. После этого ваш сервер сможет проверять личность отправителя этих запросов по цепочке доверия и общему имени (CN).

Сертификат клиента подписывается промежуточным сертификатом ЦС, DigiCert SHA2 High Assurance Server CA, а затем корневым сертификатом ЦС, DigiCert High Assurance EV Root CA. Обратите внимание, что промежуточный сертификат также подписывает сертификат для graph.facebook.com:

Проверка сертификата клиента

После настройки протокола HTTPS для получения запросов Webhooks выполните следующие действия, чтобы подтвердить клиентский сертификат и его общее имя client.webhooks.fbclientcerts.com:

Установите корневой сертификат.
Подтвердите сертификат клиента с помощью корневого сертификата.
Подтвердите общее имя (client.webhooks.fbclientcerts.com) клиентского сертификата.

Примечание. Серверы, получающие уведомления Webhooks, должны использовать протокол HTTPS. Мы всегда проверяем безопасность сертификатов с вашего сервера HTTPS.

Пример

В зависимости от конфигурации сервера описанные выше действия могут меняться. Мы покажем два примера: для Nginx и для AWS Application Load Balancer (ALB).

Nginx

Скачайте корневой сертификат (DigiCert High Assurance EV Root CA) с сервера DigiCert на свой, например /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem.

Включите mTLS, используя директивы Nginx (скриншот с примером).

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

Убедитесь, что CN во встроенной переменной Nginx $ssl_client_s_dn имеет значение "client.webhooks.fbclientcerts.com" (скриншот с примером)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

AWS Application Load Balancer (ALB)

Скачайте промежуточный сертификат (DigiCert SHA2 High Assurance Server CA) с DigiCert в контейнер S3. AWS не принимает корневой сертификат, поскольку он подписан с применением алгоритма SHA1withRSA. Промежуточный сертификат подписан с применением алгоритма SHA256withRSA и поэтому принимается.
Настройте прослушивание HTTPS в ALB, чтобы включить mTLS с хранилищем доверенных сертификатов, содержащим сертификат из контейнера S3 (скриншот с примером).
В коде своего приложения извлеките CN из заголовка HTTP “X-Amzn-Mtls-Clientcert-Subject” и убедитесь, что оно имеет значение “client.webhooks.fbclientcerts.com”.

Дальнейшие действия

Теперь, когда вы знаете, как настроить Webhooks, ознакомьтесь с дополнительными статьями, в которых описана настройка Webhooks для конкретных продуктов.