Входящие вебхуки MAX в Joomla
Настройка подписки MAX, проверка секрета и разрешённых чатов, обработка входящих событий через типизированный WebhookEvent в Joomla.
Настройка подписки
- Включите и настройте
System - WT Max, сохраните токен бота. - На вкладке «Вебхуки» включите входящие вебхуки. Пустое поле секрета заполняется автоматически при открытии формы.
- Сохраните параметры и повторно откройте форму. Для подписки должны использоваться уже сохранённые настройки.
- При необходимости заполните «Разрешённые chat_id»: каждый ID на отдельной строке. Для подписки можно выбрать
message_createdиmessage_callback. - Нажмите кнопку создания подписки. Проверьте результат и список подписок текущего сайта.
Webhook URL формируется плагином автоматически:
https://example.com/index.php?option=com_ajax&plugin=wtmax&group=system&format=raw&action=webhook&secret=YOUR_WEBHOOK_SECRET
YOUR_WEBHOOK_SECRET — условное обозначение. Используйте URL из настроек своего сайта. Секрет вебхука и токен бота — разные значения. После смены домена или секрета сохраните параметры и пересоздайте подписку с актуальными данными.
По требованиям MAX к подпискам, обработчик должен быть доступен по HTTPS на порту 443 с доверенным сертификатом и полной цепочкой. Он должен отвечать HTTP 200 в пределах 30 секунд. Тяжёлую обработку лучше передавать в очередь.
Что проверяет плагин
До вызова пользовательских обработчиков WT Max проверяет включение вебхуков, непустой сохранённый секрет, его совпадение одновременно с query-параметром secret и заголовком X-Max-Bot-Api-Secret, а затем непустое корректное JSON-тело.
Пустой список разрешённых чатов допускает все запросы, прошедшие эти проверки. При заполненном списке плагин извлекает chat_id из получателя сообщения и пропускает только совпавшие ID. События без такого ID также игнорируются. Это существенно для событий, не содержащих объект сообщения.
Если чат не разрешён, событие Joomla не вызывается и обработчик возвращает ignored. После успешных проверок вызывается onWtmaxIncomingWebhook для плагинов групп system и wtmax.
Пример обработчика Joomla
Ниже класс расширения плагина, а не полный установочный пакет. Для своего плагина добавьте манифест и регистрацию сервиса Joomla, установите и включите его.
<?php
declare(strict_types=1);
namespace Joomla\Plugin\System\Example\Extension;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use Webtolk\Wtmax\Event\WebhookEvent;
defined('_JEXEC') or die;
final class Example extends CMSPlugin implements SubscriberInterface
{
public static function getSubscribedEvents(): array
{
return ['onWtmaxIncomingWebhook' => 'handleWtmaxWebhook'];
}
public function handleWtmaxWebhook(WebhookEvent $event): void
{
if ($event->getUpdateType() !== 'message_created') {
return;
}
$message = $event->getMessage();
$chatId = $event->getChatId();
if ($message === null || $chatId === null) {
return;
}
$text = $message->getBody()?->getText() ?? '';
$data = $event->getData();
// Здесь разместите логику вашего расширения.
// Повторная доставка одного события не должна повторять бизнес-операцию.
}
}
Контракт WebhookEvent
getData(): array— исходный декодированный JSON.getUpdate(): ?Webtolk\Max\Entity\Update— типизированный объект SDK.getUpdateType(): ?string— тип обновления.getMessage(): ?Webtolk\Max\Entity\Message— сообщение, если оно есть в событии.getChatId(): ?int— ID, определённый системным плагином.getAllowedChatIds(): arrayиisAllowedChat(): bool— сведения о проверке разрешённых чатов.
Для message_callback сначала проверяйте тип события и читайте соответствующие данные из getData() или getUpdate(); сообщение может отсутствовать. MAX может повторять доставку, поэтому обработчики должны защищать бизнес-операции от дублирования.
Удаление подписок
Список показывает подписки бота и выделяет подписки текущего сайта. Из формы WT Max удаляются только выбранные подписки текущего сайта. Отключение приёма в плагине и удаление подписки в MAX — отдельные действия.