Выбираем событие и смысл уведомления
Для сообщения «Создан заказ» используйте тему Order created. Для отслеживания изменений нужна Order updated, но она срабатывает не только при оплате: изменение адреса или заметки тоже не должно превращаться в сообщение «Оплачено».
Перед внедрением согласуйте два бизнес-события: первое создание заказа и первое подтверждение оплаты в вашей системе. Pending payment, on-hold, processing и completed отражают состояние заказа; их связь с реальной оплатой зависит от платёжного шлюза и рабочего процесса магазина. В частности, обработка заказа с оплатой при получении не доказывает зачисление денег.
Для оплаченного заказа проверяйте платёжный факт, который фиксирует ваш gateway и WooCommerce, например date_paid вместе с принятым сценарием оплаты. Если используете Action с woocommerce_payment_complete, не ожидайте стандартный полный объект заказа: action payload содержит сведения о действии и аргумент, а заказ нужно получить отдельно. Даже событие магазина не заменяет финансовую сверку с провайдером.
Настраиваем webhook в WooCommerce
Откройте WooCommerce → Settings → Advanced → Webhooks, создайте webhook и задайте понятное название. Укажите Active, тему Order created, HTTPS Delivery URL своего обработчика и отдельный случайный Secret. Секрет сохраните в конфигурации обработчика. Для Order updated создайте отдельную настройку; удобно использовать отдельный URL и секрет, чтобы сервер знал допустимую тему из своей конфигурации.
Delivery URL ведёт на ваш приёмник, а не прямо на sendMessage: WooCommerce передаёт объект заказа и собственную подпись, тогда как Telegram ожидает chat_id и text. Входящие данные нужно проверить и преобразовать.
При первой активации WooCommerce отправляет проверочный ping. В штатной реализации это form-body webhook_id=<число>, который отличается от подписанного JSON заказа. Приёмник может ответить 200 на узко распознанный ping, ничего не сохранять и не отправлять. Это проверка доступности URL, а не доказательство подлинности заказа. Любой запрос, похожий на заказ, обязан пройти HMAC-проверку.
Проверяем подпись исходного тела
Для отдельного приёмника подойдёт PHP 8.3+. Подпись X-WC-Webhook-Signature — Base64 от бинарного HMAC-SHA256 исходных байтов тела. Сначала прочитайте php://input с ограничением размера, затем проверьте подпись и только после этого декодируйте JSON. При повторном json_encode подпись может перестать совпадать.
<?php
declare(strict_types=1);
function validWooSignature(string $raw, string $signature, string $secret): bool
{
if ($secret === '' || $signature === '') {
return false;
}
$expected = base64_encode(hash_hmac('sha256', $raw, $secret, true));
return hash_equals($expected, $signature);
}
В endpoint передайте в функцию неизменённое тело, $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] и секрет из серверной конфигурации. Если заголовка нет или проверка не прошла, верните 401/403 и не создавайте задание. Ограничьте приём методом POST, размером тела и ожидаемой структурой: положительный числовой id, строки total/currency/status, массив line_items.
X-WC-Webhook-Source и X-WC-Webhook-Topic полезны для диагностики, но сами не подписаны этим HMAC. Не выбирайте секрет или доверенный адрес REST API по произвольному заголовку. Привяжите источник, секрет и допустимую тему к заранее настроенному endpoint магазина. Для повторного чтения заказа используйте фиксированный адрес своего WooCommerce и отдельные учётные данные.
Сохраняем событие до успешного ответа
Приёмник должен быстро записать событие и вернуть 2xx. Сетевую отправку Telegram выполняет worker. Если БД недоступна, успешный ответ не подтверждает сохранение: верните ошибку, зафиксируйте сбой и предусмотрите восстановление из журналов и сверку заказов. Не полагайтесь на бесконечные гарантированные повторы WooCommerce.
Храните идентификатор магазина, webhook ID, delivery ID, время приёма и исходное тело в закрытом хранилище с ограниченным сроком хранения. В нём могут быть адрес и телефон покупателя. Не публикуйте эти данные в логах веб-сервера.
Для уведомлений нужен отдельный бизнес-ключ. Пример таблицы для SQLite ниже показывает принцип: одно уведомление каждого вида по одному заказу магазина. В рабочей MariaDB используйте соответствующий синтаксис уникальности и атомарной вставки.
CREATE TABLE order_notifications (
id INTEGER PRIMARY KEY AUTOINCREMENT,
shop_id TEXT NOT NULL,
order_id INTEGER NOT NULL,
kind TEXT NOT NULL,
message TEXT NOT NULL,
state TEXT NOT NULL DEFAULT 'pending',
telegram_message_id INTEGER,
UNIQUE (shop_id, order_id, kind)
);
Запись входящего события и создание pending-уведомления делайте в одной транзакции. Для нового заказа kind=created; для первого подтверждённого платёжного события kind=paid. Если бизнесу нужны отдельные возвраты и повторные оплаты, в ключ придётся добавить ID конкретной операции. Один delivery ID не защищает от нескольких разных обновлений одного заказа.
Собираем сообщение менеджеру
Начните с номера, статуса, суммы с валютой и нескольких товарных позиций. Полные реквизиты и адреса оставьте в защищённой админке. Ссылку на заказ формируйте из настроенного домена и маршрута вашего магазина, учитывая используемый режим админки WooCommerce; URL из входящего JSON без проверки не используйте.
Функция ниже принимает уже проверенный объект заказа. Названия не проходят через parse_mode, поэтому пользовательские символы не испортят HTML Telegram. mbstring необходим для ограничения длины. Денежную строку сохраняем как пришла, без преобразования во float.
<?php
declare(strict_types=1);
function wooOrderText(array $order): string
{
$lines = [
'Создан заказ №'.(string) $order['id'],
'Статус: '.mb_substr((string) $order['status'], 0, 60),
'Сумма: '.mb_substr((string) $order['total'], 0, 40).' '.
mb_substr((string) $order['currency'], 0, 8),
];
foreach (array_slice($order['line_items'], 0, 8) as $item) {
$name = preg_replace('/\s+/u', ' ', (string) $item['name']);
$lines[] = '• '.mb_substr($name ?? '', 0, 160).' × '.
mb_substr((string) $item['quantity'], 0, 12);
}
if (count($order['line_items']) > 8) {
$lines[] = 'Остальные позиции — в заказе магазина.';
}
return implode("\n", $lines);
}
Worker передаёт результат в sendMessage как text, а chat_id берёт из своей конфигурации. Добавьте бота в тестовую группу менеджеров и проверьте право отправки. Успех фиксируйте по ответу ok=true и сохранённому message_id, а не только по завершению HTTP-запроса.
Что делать с повтором и потерянным ответом
Worker атомарно переводит pending в processing; только процесс, изменивший строку, выполняет отправку. После успешного ответа сохраняет sent и message_id. При явном отказе Telegram записывает причину; при подтверждённом 429 планирует ограниченный повтор с retry_after. При таймауте или падении после отправки оставляет unknown для разбора.
Не возвращайте зависшее processing автоматически в pending: сообщение уже могло уйти. Уникальная строка в БД защищает планирование, но не объединяет отправку Telegram и запись результата в одну транзакцию. Подробнее — в разборе дублей сообщений.
В WooCommerce проверяйте Status → Logs и источник webhooks-delivery. После последовательных ошибок доставка может быть отключена. Исправьте причину и проверьте статус webhook; восстановление настройки само по себе не доказывает доставку пропущенных заказов. Сверьте нужный период с базой магазина и бизнес-ключами уведомлений.
Проверяем магазин до рабочего запуска
Новый неоплаченный заказ даёт «Создан заказ», а не «Оплачено».
Правильная подпись принимается; изменение одного байта тела даёт отказ.
Ping возвращает 200 и не создаёт Telegram-уведомление.
Две доставки одного события и два обновления заказа не дублируют первое уведомление об оплате.
Сбой БД не подтверждается успешным ответом; падение worker после отправки попадает в разбор неизвестного исхода.
Проверьте онлайн-оплату, оплату при получении, ручную смену статуса и отмену отдельно для вашего gateway.
Приведённые функции — части приёмника и worker. Их нужно встроить в вашу очередь и обработчик; настройка webhook сама не создаёт приложение. Полный запуск конкретного WordPress-магазина и платёжного модуля требует отдельного тестового заказа.
Если сообщения идут через BotGate
На стороне магазина проверка WooCommerce остаётся прежней. Меняется серверный транспорт вызова sendMessage: BotGate API. Не путайте секрет WooCommerce с API-ключом BotGate или подписью входящих Telegram webhook. Шлюз не определяет, был ли оплачен заказ.