Примеры вебхуков для аккаунтов и номеров телефонов WhatsApp

Полный каталог, сгенерированный на основе схемы, см. в разделе Все примеры.

Что это такое

Обрабатывайте события проверки, обновления и удаления бизнес-аккаунтов, а также удаления номеров телефонов, проверки отображаемых имен, качества и обновления Business Username. Маршрутизируйте каждую полезную нагрузку по точному значению события type: для событий аккаунтов используется whatsappBusinessAccount, а для событий номеров телефонов — whatsappPhoneNumber.

Перед началом работы

Создайте публичный эндпоинт HTTPS в вашем приложении.
Настройте эндпоинт вебхука YCloud для нужных типов событий.
Надежно сохраните секретный ключ подписи эндпоинта.
Сделайте обработку событий идемпотентной.

Принцип работы

YCloud отправляет HTTP-запрос POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные операции асинхронно.

Запрос

Ниже приведены сценарии запросов, доставляемых на ваш URL вебхука. Используйте id события как идентификатор доставки, а type — для маршрутизации полезной нагрузки.

Ответ

Возвращайте статус 2xx после принятия события.

HTTP/1.1 200 OK

Информацию о настройке эндпоинта, проверке подписи и поведении при повторных попытках см. в разделе Настройка вебхуков.

Удаление аккаунта

Используйте whatsapp.business_account.deleted для обработки события удаления WhatsApp Business Account. Обратитесь к полю whatsappBusinessAccount.id, чтобы определить затронутый WABA.

Запрос

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Поля удаления появляются непосредственно внутри whatsappBusinessAccount, если они доступны.

Поле	Значение
`id`	Идентификатор затронутого WhatsApp Business Account.
`removedReason`	Исходная причина удаления. Известные значения приведены ниже.
`removedInitiatedBy`	`USER` для удаления, инициированного пользователем WhatsApp, или `SYSTEM` для удаления, инициированного Meta.
`removedTime`	Время получения события удаления сервисом YCloud в формате RFC 3339.

К известным значениям removedReason относятся:

Значение	Значение
`ACCOUNT_DISCONNECTED`	Аккаунт был отключен из-за применения мер воздействия или в связи с явным удалением аккаунта WhatsApp.
`BUSINESS_DOWNGRADE`	Номер телефона был зарегистрирован в пользовательском приложении WhatsApp.
`CHANGE_NUMBER`	Номер телефона WhatsApp был изменен.
`COMPANION_INACTIVITY`	Дополнительное устройство было неактивно около 30 дней.
`PRIMARY_INACTIVITY`	Основное устройство было неактивно около 30 дней.
`USER_RE_REGISTERED`	WhatsApp был повторно зарегистрирован на новом устройстве.

Сохраняйте неизвестные значения причин и инициаторов. Выполняйте дедупликацию доставок по id события и корректно обрабатывайте отсутствие полей удаления.

Authentication-International Rate Eligibility

С 1 июня 2024 года вводится новый тариф authentication-international. Этот тариф будет действовать в следующих странах:

1 июня 2024 г. – Индонезия (телефонный код страны +62, код страны ID)
1 июля 2024 г. – Индия (телефонный код страны +91, код страны IN)

Дополнительную информацию см. в разделе Authentication-International Rate Eligibility . Вебхук whatsapp.business_account.updated будет активирован, если ваш бизнес будет признан подходящим для международных тарифов. Вебхук будет содержать время начала действия тарифа для каждой страны с тарифом authentication-international.

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Если за сообщение взимается плата по тарифу authentication-international, поле whatsappMessage.pricingCategory в вебхуках whatsapp.message.updated будет иметь значение authentication_international. Вот пример:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и передавайте медленные или подверженные ошибкам задачи в асинхронный обработчик.

Обновление основного местоположения бизнеса

Ваше основное местоположение бизнеса — это страна, в которой зарегистрирован ваш бизнес. С 1 мая 2024 года оно будет отображаться в Business Manager в поле Primary Business Location. Если Meta сможет определить страну, в которой зарегистрирован ваш бизнес, будет отправлен вебхук whatsapp.business_account.updated с двухзначным кодом страны. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Обновление лимита регистрации номеров телефонов

Meta отправляет обновление бизнес-возможностей для WABA при изменении лимита регистрации номеров телефонов соответствующего Business Portfolio или WABA. YCloud доставляет его как whatsapp.business_account.updated с updateEvent=BUSINESS_CAPABILITY_UPDATE. Этот webhook работает на уровне WABA: whatsappBusinessAccount.id — это WABA ID из записи webhook от Meta. Meta в настоящее время сообщает о maxPhoneNumbersPerBusiness и maxPhoneNumbersPerWaba в отдельных обновлениях. Не считайте их взаимоисключающими: обрабатывайте каждое поле независимо и принимайте оба, если в будущем обновлении они поступят вместе. Значение 0 является допустимым. Ниже приведен пример обновления лимита номеров телефонов для WABA:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и обновляйте только то поле лимита, которое включено в полезную нагрузку.

Нарушение в аккаунте

При получении события whatsapp.business_account.updated со значением ACCOUNT_VIOLATION в whatsappBusinessAccount.updateEvent проверьте whatsappBusinessAccount.violationType, чтобы определить зафиксированное нарушение правил. Типы и описания нарушений см. в разделе Meta Policy enforcement violations. Meta может со временем обновлять этот список. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SCAM"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и передавайте медленные или подверженные сбоям задачи асинхронному обработчику.

Ограничение аккаунта

Если бизнес-аккаунты повторно нарушают Условия использования WhatsApp Business или правила в категориях повышенного риска (таких как рассылка спама, контент для взрослых, продажа алкоголя и табака, наркотики, азартные игры и небезопасные добавки), они могут столкнуться с ограничениями на отправку сообщений, длительность которых постепенно увеличивается. Для Utility Direct Send см. Уведомления Direct Send, где описана полезная нагрузка YCloud ACCOUNT_RESTRICTION. Информацию о типах нарушений и ограничениях, характерных для Direct Send, см. в документации Meta Webhook для ограничения аккаунта. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      }
    ]
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Ограничение Utility Direct Send

Вы получаете whatsapp.business_account.updated, когда Meta ограничивает Utility Direct Send после повторного неправомерного использования категорий. В этом примере показано ограничение на семь дней.

Запрос

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Используйте whatsappBusinessAccount.id, чтобы определить затронутый WABA и приостановить его рабочий процесс Utility Direct Send. Значение поля violationType указывает причину, restrictions[].restrictionType — затронутую возможность, а restrictions[].expiration — срок окончания (если он указан). Успешная проверка одного шаблона не приводит к автоматическому снятию ограничения на уровне аккаунта. См. раздел Ограничения и уведомления Direct Send.

Отключение аккаунта

Аккаунты WhatsApp Business могут быть отключены, если компания не вносит изменения после многочисленных предупреждений, ограничений функций или блокировок. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Восстановление аккаунта

Вы можете обжаловать решение о блокировке WhatsApp Business Account, чтобы восстановить его. После одобрения статус проверки аккаунта меняется на APPROVED. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Проверка бизнес-аккаунта

Используйте whatsapp.business_account.reviewed, когда WhatsApp Business Account прошел проверку.

Запрос

{
  "id": "evt_example_whatsapp_business_account_reviewed",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "accountReviewStatus": "APPROVED"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Идентифицируйте WABA с помощью id. В поле decision содержится решение по проверке (APPROVED или REJECTED), а в accountReviewStatus — статус проверки аккаунта (если указан). Не маршрутизируйте это событие как whatsapp.business_account.updated.

Удаление номера телефона

Используйте whatsapp.phone_number.deleted, когда удаляется бизнес-номер телефона WhatsApp.

Запрос

{
  "id": "evt_example_whatsapp_phone_number_deleted",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Используйте whatsappPhoneNumber.id, чтобы определить удаленный номер телефона, и wabaId, чтобы сопоставить его с аккаунтом. Это событие относится к номеру телефона; не считайте его удалением всей WABA.

Проверка отображаемого имени номера телефона

Используйте whatsapp.phone_number.name_updated, когда отображаемое имя бизнес-номера телефона одобрено или отклонено.

Запрос

{
  "id": "evt_example_whatsapp_phone_number_name_updated",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Проверьте decision и указанные поля статуса имени. Поле newNameStatus описывает новый запрос отображаемого имени, requestedVerifiedName указывает последнее запрошенное имя, а rejectionReason содержит причину отклонения (при наличии). Проверка отображаемого имени выполняется отдельно от обновления Business Username.

Обновление качества номера телефона

Используйте whatsapp.phone_number.quality_updated для изменений статуса качества бизнес-номера телефона.

Запрос

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

Ответ

Подтверждайте доставку только после надежного сохранения события.

HTTP/1.1 200 OK

Объяснение

Изучите qualityRating (GREEN, YELLOW или RED) и qualityUpdateEvent, чтобы понять суть обновления. messagingLimit — это уровень телефонного номера; whatsappBusinessManagerMessagingLimit — лимит бизнес-портфолио владельца. Разделяйте эти поля и обновляйте только значения, переданные в событии.

Business Username активирован

Используйте whatsapp.phone_number.business_username_updated для синхронизации Business Username телефонного номера.

Запрос

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Ответ

Подтверждайте доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

businessUsername — это активное имя пользователя без начального символа @. Считывайте businessUsernameStatus и businessUsernameUpdatedAt вместе с id телефонного номера. Не путайте это значение с подтвержденным отображаемым именем.

Запрос на Business Username зарезервирован

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

Запрос

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

Ответ

Подтверждайте доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

В этом примере businessUsername остается acme.support, в то время как requestedBusinessUsername имеет значение acme.help. Статус reserved описывает ожидающий запрос, а не активацию замены. Принимайте устаревшее значение pending_review при чтении более старых событий; для новых операций записи используется reserved.

​Что это такое

​Перед началом работы

​Принцип работы

​Запрос

​Ответ

​Удаление аккаунта

​Запрос

​Ответ

​Пояснение

​Authentication-International Rate Eligibility

​Запрос

​Ответ

​Пояснение

​Обновление основного местоположения бизнеса

​Запрос

​Ответ

​Пояснение

​Обновление лимита регистрации номеров телефонов

​Запрос

​Ответ

​Объяснение

​Нарушение в аккаунте

​Запрос

​Ответ

​Объяснение

​Ограничение аккаунта

​Запрос

​Ответ

​Объяснение

​Ограничение Utility Direct Send

​Запрос

​Ответ

​Объяснение

​Отключение аккаунта

​Запрос

​Ответ

​Объяснение

​Восстановление аккаунта

​Запрос

​Ответ

​Объяснение

​Проверка бизнес-аккаунта

​Запрос

​Ответ

​Объяснение

​Удаление номера телефона

​Запрос

​Ответ

​Объяснение

​Проверка отображаемого имени номера телефона

​Запрос

​Ответ

​Объяснение

​Обновление качества номера телефона

​Запрос

​Ответ

​Объяснение

​Business Username активирован

​Запрос

​Ответ

​Пояснение

​Запрос на Business Username зарезервирован

​Запрос

​Ответ

​Пояснение

Что это такое

Перед началом работы

Принцип работы

Запрос

Ответ

Удаление аккаунта

Запрос

Ответ

Пояснение

Authentication-International Rate Eligibility

Запрос

Ответ

Пояснение

Обновление основного местоположения бизнеса

Запрос

Ответ

Пояснение

Обновление лимита регистрации номеров телефонов

Запрос

Ответ

Объяснение

Нарушение в аккаунте

Запрос

Ответ

Объяснение

Ограничение аккаунта

Запрос

Ответ

Объяснение

Ограничение Utility Direct Send

Запрос

Ответ

Объяснение

Отключение аккаунта

Запрос

Ответ

Объяснение

Восстановление аккаунта

Запрос

Ответ

Объяснение

Проверка бизнес-аккаунта

Запрос

Ответ

Объяснение

Удаление номера телефона

Запрос

Ответ

Объяснение

Проверка отображаемого имени номера телефона

Запрос

Ответ

Объяснение

Обновление качества номера телефона

Запрос

Ответ

Объяснение

Business Username активирован

Запрос

Ответ

Пояснение

Запрос на Business Username зарезервирован

Запрос

Ответ

Пояснение