Перейти к содержанию
10 минут чтения
Тема: Практика WooCommerce · WordPress · Webhook

Как отправлять уведомления о заказах WooCommerce в Telegram

Для примера интернет-магазин хочет сообщать менеджеру о новых заказах в Telegram-группу. WordPress передаст событие на отдельный обработчик, тот сохранит его, а worker отправит сообщение. Отдельно разберём оплату: создание заказа ещё не означает поступление денег.

Выбираем событие и смысл уведомления

Для сообщения «Создан заказ» используйте тему 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 · Функция проверки WooCommerce
<?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 используйте соответствующий синтаксис уникальности и атомарной вставки.

SQL · Очередь уведомлений для учебного приёмника
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 · Текст уведомления о создании заказа
<?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. Шлюз не определяет, был ли оплачен заказ.