Вебхуки

Обновлено:

Где: Настройки > Интеграции > Вебхуки

Для чего это нужно:

«Пересылайте входящие события на ваш сервер». SyBox передает копию каждого выбранного события WhatsApp на адрес вашего сервера в реальном времени. Вебхуки работают только для номеров WhatsApp. События из Messenger, Instagram, Telegram, эл. почты и SMS не отправляются.

Кто может открыть: главный администратор и сотрудники с правом «Управление номерами WhatsApp». Для создания вебхука или включения приостановленного требуется также право «Показывать номер контакта», поскольку данные содержат реальные номера клиентов.

События на выбор:

  • «Входящее сообщение»: клиент прислал сообщение.
  • «Статус сообщения»: отправленное вами сообщение отправлено, доставлено, прочитано или не ушло.
  • «Реакция»: клиент поставил реакцию на сообщение.
  • «Расшифровка голоса» (дополнительно): голосовое сообщение задерживается на короткое время (до двух минут), чтобы отправить его расшифровку вместе с ним. По умолчанию выключено.

Как добавить вебхук

  1. Перейдите в Настройки > Интеграции > Вебхуки.
    Settings, Webhooks: an active webhook with its last result, and the "Add webhook" button
  2. Нажмите «Добавить вебхук».
    The new webhook window: its name and the address it calls
  3. Введите «Название».
  4. Введите «URL назначения». Это должен быть «Публичный https-адрес, доступный для нас». Обычные адреса http, а также частные и локальные IP-адреса не принимаются.
  5. В блоке «События» включите хотя бы одно событие. «Входящее сообщение» включено по умолчанию.
  6. Необязательно: включите «Расшифровка голоса», чтобы получать голосовые вместе с текстом.
  7. В блоке «Номера» оставьте «Все номера» для всех номеров WhatsApp. Или отключите этот пункт и отметьте только нужные номера.
  8. Нажмите Сохранить.
  9. В окне появится «Ключ подписи». «Скопируйте сейчас — показывается только один раз». Сохраните его на своем сервере.

О доставке запросов:

  • Данные отправляются в том же формате, что и в стандартных вебхуках WhatsApp от Meta.
  • Каждый запрос подписывается секретным ключом так же, как вебхуки Meta. Если ваш сервер уже проверяет подпись Meta, он сможет проверять запросы SyBox, используя секрет SyBox.
  • Если ваш сервер не отвечает успешным кодом, SyBox повторяет попытки с увеличивающимися интервалами в течение примерно одного часа. Затем попытки прекращаются.
  • Одно и то же событие может прийти дважды, например из-за тайм-аута. Сервер должен уметь обрабатывать дубли.

Как протестировать вебхук

  • В SyBox нет кнопки тестовой отправки вебхуков. Чтобы проверить работу:
  • Убедитесь, что вебхук включен и привязан к используемому номеру.
  • Отправьте сообщение в WhatsApp на этот номер с другого телефона.
    To test a webhook: "HTTP 200" marked on the screen in SyBox
  • Вернитесь в Настройки > Интеграции > Вебхуки. На карточке отобразится последний ответ вашего сервера и время. Успешный ответ (например, «HTTP 200») будет зеленым, ошибка — красной. Статус «Последняя доставка: никогда» означает, что события еще не отправлялись.

Как изменить, приостановить или удалить вебхук

  1. Нажмите Редактировать, чтобы изменить название, адрес, события или номера.
    To edit, pause or delete a webhook: "Edit" marked on the screen in SyBox
  2. Чтобы сменить ключ подписи, укажите новый в поле «Ключ подписи». Оставьте поле пустым, чтобы не менять его («Оставьте пустым, чтобы сохранить текущий ключ»).
  3. Нажмите «Включить» / «Отключить», чтобы приостановить отправку. События, поступающие во время паузы, встают в очередь. Если включить вебхук вскоре, они будут доставлены.
  4. Нажмите «Удалить» и подтвердите: «Удалить этот вебхук?».

Правила и сообщения:

  • Название и URL назначения обязательны, также должно быть выбрано хотя бы одно событие. Иначе появится ошибка: «Неполные данные».
  • Непубличный адрес без https отклоняется с ошибкой: «Публичный https-адрес, доступный для нас».
Я потерял ключ подписи.

Посмотреть его снова нельзя. Откройте вебхук на редактирование, введите новый секрет в поле «Ключ подписи», сохраните и пропишите его на сервере.

На вебхук ничего не приходит.

Проверьте 4 момента: (1) Вебхук включен. (2) Выбрано хотя бы одно событие. (3) Привязан нужный номер WhatsApp или выбрано «Все номера». (4) В рабочей области вообще подключен номер WhatsApp (вебхуки работают только для них). Затем проверьте статус последней доставки на карточке.

На карточке красная ошибка, например HTTP 404 или 500.

SyBox достучался до адреса, но сервер ответил ошибкой. Проверьте правильность адреса и логи сервера.

Не могу создать вебхук: пишет, что нет доступа.

Для создания и включения вебхука нужны права «Управление номерами WhatsApp» и «Показывать номер контакта». Обратитесь к администратору.