Веб-хуки | Документация для разработчиков
Вебхуки
Обновлено: 2 декабря 2025 г
В этом документе описываются веб-хуки и способы их использования платформой WhatsApp Business.
Вебхуки — это HTTP-запросы, содержащие JSON-данные, которые отправляются с серверов Meta на указанный вами сервер. Платформа WhatsApp Business использует вебхуки для информирования вас о входящих сообщениях, статусе исходящих сообщений и другой важной информации, такой как изменения статуса вашей учетной записи, обновления возможностей обмена сообщениями и изменения оценок качества ваших шаблонов.
Например, это веб-хук, описывающий сообщение, отправленное пользователем WhatsApp компании:
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=", "timestamp": "1749416383", "type": "text", "text": { "body": "Есть ли он в другом цвете?" } } ] }, "field": "messages" } ] } ] }Создайте конечную точку веб-перехватчика
Для приема веб-хуков необходимо создать и настроить конечную точку веб-хука. Инструкции по созданию собственной конечной точки см. в нашем документе «Создание конечной точки веб-хука».
Если вы пока не готовы создать собственную конечную точку, вы можете создать тестовую конечную точку веб-перехватчика , которая будет выводить данные веб-перехватчика в консоль. Однако обратите внимание, что прежде чем вы сможете использовать свое приложение в производственной среде, вы должны создать собственную конечную точку.
Разрешения
Для получения веб-хуков вам потребуются следующие разрешения:
Если вы являетесь непосредственным разработчиком, используйте системного пользователя для предоставления приложению этих разрешений при генерации системного токена .
Если вы являетесь поставщиком решений и вам необходимы эти разрешения для предоставления соответствующих услуг вашим бизнес-клиентам, вы должны получить одобрение на расширенный доступ к этим разрешениям через процедуру проверки приложения , прежде чем ваши бизнес-клиенты смогут предоставить вашему приложению эти разрешения во время регистрации.
Поля
После создания и настройки конечной точки веб-перехватчика (или настройки тестовой конечной точки веб-перехватчика ) используйте управления приложением > WhatsApp > Конфигурация , чтобы подписаться на отдельные поля веб-перехватчика.
Обратите внимание, что если вы создали приложение, используя взаимодействия с клиентами через WhatsApp , перейдите в Панель управления приложениями > Сценарии использования > Настройка > Конфигурация .
| Название поля | Описание |
|---|---|
Веб account_alerts лимита сообщений , профиля компании и официального бизнес-аккаунта для корпоративного телефонного номера . | |
Веб account_review_update уведомляет вас о том, что учетная запись WhatsApp Business была проверена на соответствие нашим правилам. | |
-хук account_update уведомляет бизнес-подтверждения, предоставленных партнером WhatsApp Business , о международной аутентификации или об основном местоположении бизнеса, когда учетная запись передается партнеру по решениям , о нарушениях политики или условий , об удалении, повторном подключении или об удалении учетной записи. | |
automatic_events , который отправил вам сообщение через вашу рекламу Click to WhatsApp, если вы включили по автоматическим событиям . | |
Веб business_capability_update уведомляет вас об изменениях в возможностях бизнес-аккаунта WhatsApp или бизнес-портфеля ( лимиты на сообщения , лимиты на номера телефонов и т. д.). | |
Веб истории используется для синхронизации истории чатов в приложении WhatsApp Business для бизнес-клиентов, подключенных поставщиком решений. | |
Веб message_template_components_update уведомляет вас об изменениях в компонентах шаблона. | |
Веб message_template_quality_update оценке качества шаблона . | |
Веб message_template_status_update уведомляет вас об изменениях статуса существующего шаблона. | |
Веб сообщений описывает сообщения, отправленные пользователем WhatsApp компании, а также статус сообщений, отправленных компанией пользователю WhatsApp. | |
Веб -хук partner_solutions описывает изменения статуса многопартнерского решения . | |
перехватчик payment_configuration_update уведомляет вас об изменениях в конфигурации платежей для Payments API India и Payments API Brazil . | |
Веб phone_number_name_update уведомляет вас о проверки отображаемого имени . | |
Веб phone_number_quality_update уровня пропускной способности бизнес-телефонного номера . | |
Веб безопасности уведомляет вас об изменениях в настройках безопасности корпоративного телефонного номера. | |
Веб smb_app_state_sync используется для синхронизации контактов пользователей приложения WhatsApp Business, которые были подключены через поставщика решений. | |
Веб smb_message_echoes уведомляет вас о сообщениях, отправленных через приложение WhatsApp Business или сопутствующее («связанное») устройство бизнес-клиентом, подключенным к Cloud API через поставщика решений. | |
Веб template_category_update категории шаблона . | |
Веб user_preferences настройках получения маркетинговых сообщений пользователем WhatsApp . |
Переопределение веб-хуков
определенных полей веб-перехватчика вы можете использовать альтернативную конечную точку веб-перехватчика. Это может быть полезно для целей тестирования или если вы являетесь поставщиком решений и хотите использовать уникальные конечные точки веб-перехватчика для каждого из ваших подключенных клиентов.
Чтобы узнать, как переопределять веб-хуки, ознакомьтесь с нашим
размер полезной нагрузки
Размер полезной нагрузки веб-хука может достигать 3 МБ.
Сбой доставки веб-хука
Если мы отправим запрос веб-хука на вашу конечную точку, и ваш сервер ответит кодом состояния HTTP, отличным от 200, или если мы не сможем доставить веб-хук по другой причине, мы будем продолжать попытки с уменьшающейся частотой до тех пор, пока запрос не будет успешно выполнен, в течение до 7 дней.
Обратите внимание, что повторные попытки будут отправлены всем приложениям, подписанным на веб-хуки (и соответствующие поля) для бизнес-аккаунта WhatsApp. Это может привести к дублированию уведомлений веб-хуков.
Взаимная TLS
Инструкции по включению и использованию mTLS см. в документе Graph API, посвященном mTLS для веб-хуков
IP-адреса
IP-адреса наших веб-серверов можно получить, выполнив в терминале следующую команду:
whois - ч кто . радб . сеть — '-i происхождение AS32934' | grep '^route' | awk '{print $2}' | сортироватьВы также можете использовать нашу геолокационную ленту, чтобы загрузить CSV-файл со списком наших IP-адресов.
Однако обратите внимание, что мы периодически меняем наши IP-адреса, поэтому, чтобы избежать необходимости повторного формирования списка разрешенных IP-адресов, мы рекомендуем использовать mTLS .
Поиск неисправностей
Если вы не получаете веб-хуки: