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

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

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

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

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

Создание конечной точки

Конечная точка должна обрабатывать два типа HTTPS-запросов: запросы подтверждения и уведомления о событиях. Так как оба типа запросов используют протокол HTTPS, на вашем сервере должен быть настроен и установлен действующий сертификат TLS или SSL. Самозаверенные сертификаты не поддерживаются.

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

Запросы подтверждения

При настройке продукта Webhooks на панели приложений мы отправляем на URL вашей конечной точки запрос GET. Запросы подтверждения включают в себя URL вашей конечной точки со следующими параметрами строки запроса. Они будут выглядеть примерно так:

Пример запроса подтверждения

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

Параметр	Пример значения	Описание
`hub.mode`	`subscribe`	Этот параметр всегда имеет значение `subscribe`.
`hub.challenge`	`1158201444`	Значение типа `int`, которое нужно вернуть нам.
`hub.verify_token`	`meatyhamhock`	Строка, которую мы берем из поля Маркер подтверждения на панели вашего приложения. Вы зададите ее во время настройки Webhooks.

Примечание.PHP преобразует точки (.) в названиях параметров в знаки подчеркивания (_).

Обработка запросов подтверждения

Когда ваша конечная точка получает запрос подтверждения, она должна:

проверить, совпадает ли значение hub.verify_token со строкой, которую вы задали в поле Подтвердить маркер на панели приложений при настройке продукта Webhooks (сейчас она не задана);
Передать в ответ значение hub.challenge.

Если вы настраиваете продукт Webhooks на панели приложений и инициируете таким образом запрос подтверждения, вы увидите на панели, правильно ли ваша конечная точка подтвердила запрос. Если вы настраиваете продукт Webhooks с помощью конечной точки /app/subscriptions API Graph, этот API отправит ответ об успешном или неудачном подтверждении.

Уведомления о событиях

При настройке продукта Webhooks вы подписываетесь на определенные поля (fields) типа object (например, на поле photos объекта user). При изменении одного из этих полей мы будем отправлять на вашу конечную точку запрос POST с полезными данными JSON, описывающими изменение.

Например, если вы подписались на поле photos объекта user и один из пользователей вашего приложения опубликовал фото, мы отправим вам примерно такой запрос POST:

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

Полезные данные

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

Они всегда имеют формат JSON, поэтому их можно анализировать с помощью стандартных методов и пакетов для анализа JSON.

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

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

Свойство	Описание	Тип
`object`	Тип объекта (например, `user`, `page` и т. д.)	`string`
`entry`	Массив, который содержит объект, описывающий изменения. Изменения, внесенные в разные объекты одного типа, могут объединяться.	`array`
`id`	ID объекта	`string`
`changed_fields`	Массив строк с названиями измененных полей. Добавляется, только если вы отключили настройку Добавить значения при настройке продукта Webhooks на панели приложения.	`array`
`changes`	Массив, который содержит объект, описывающий измененные поля и их новые значения. Добавляется, только если вы включили настройку Добавить значения при настройке продукта Webhooks на панели приложения.	`array`
`time`	Метка времени UNIX, указывающая, когда было отправлено уведомление о событии (это не время внесения изменения, которое активировало уведомление).	`int`

Проверка полезных данных

Мы подписываем полезные данные уведомлений о событии с использованием алгоритма SHA256 и добавляем эту подпись в заголовок X-Hub-Signature-256 запроса, добавляя перед ней sha256=. Проверять полезные данные не обязательно, но желательно.

Как проверить полезные данные:

Сгенерируйте подпись SHA256, используя полезные данные и секрет приложения.
Сравните свою подпись с подписью в заголовке X-Hub-Signature-256 (после sha256=). Если подписи совпадают, полезные данные подлинны.

Ответы на уведомления о событиях

В ответ на все уведомления о событиях ваша конечная точка должна отправлять код 200 OK HTTPS.

Частота

Уведомления о событиях агрегируются и отправляются пакетом (не более 1000 обновлений). При этом пакетная обработка не гарантируется, поэтому настройте на своих серверах обработку каждого Webhooks по отдельности.

В случае сбоя отправки обновления на сервер мы сразу же повторим попытку. Затем, в течение следующих 36 часов, мы будет отправлять обновления повторно, постепенно увеличивая интервалы времени между попытками. В таких случаях ваш сервер должен выполнить дедупликацию. Ответы, не принятые в течение этих 36 часов, будут удалены.

Примечание. Частота, с которой отправляются уведомления о событиях Messenger, будет другой. Дополнительную информацию см. в документации по Webhooks платформы Messenger.

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

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

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

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

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

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