WooCommerce: автоматическое изменение статусов заказов при оплате через Webhook

Диагностика проблемы с изменением статуса заказа в WooCommerce

Часто при интеграции нестандартных платёжных шлюзов возникает проблема: платежи проходят, но статус заказа в WooCommerce не меняется автоматически. Это приводит к задержкам в выполнении заказов и недовольству клиентов.

Основные признаки проблемы:

• Заказы остаются в статусе «ожидает оплаты» даже после успешного платежа.
• Платёжный шлюз отправляет уведомления (Webhook), но WooCommerce их не обрабатывает.
• Отсутствуют записи в логах или ошибки в обработке уведомлений.

Пошаговое решение: автоматическое обновление статусов через Webhook

1. Проверка и настройка Webhook на стороне платёжного шлюза

Убедитесь, что Webhook настроен на передачу корректных данных в формате JSON на endpoint вашего сайта, например, https://site.ru/wp-json/wc/v3/webhook-handler. Важно, чтобы в payload были уникальные идентификаторы заказа (ID или номер), статус оплаты и сумма.

2. Создание кастомного REST API endpoint в WooCommerce для приёма Webhook

Добавьте в functions.php или отдельный плагин следующий код:

add_action('rest_api_init', function () {
    register_rest_route('wc/v3', '/webhook-handler', [
        'methods' => 'POST',
        'callback' => 'handle_payment_webhook',
        'permission_callback' => '__return_true',
    ]);
});

function handle_payment_webhook(WP_REST_Request $request) {
    $data = $request->get_json_params();

    if (empty($data['order_id']) || empty($data['payment_status'])) {
        return new WP_REST_Response(['error' => 'Missing required data'], 400);
    }

    $order_id = intval($data['order_id']);
    $payment_status = sanitize_text_field($data['payment_status']);

    $order = wc_get_order($order_id);
    if (!$order) {
        return new WP_REST_Response(['error' => 'Order not found'], 404);
    }

    if ($payment_status === 'paid') {
        // Пример: переводим заказ в статус 'processing'
        $order->update_status('processing', 'Payment confirmed via webhook');
    } elseif ($payment_status === 'failed') {
        $order->update_status('failed', 'Payment failed via webhook');
    }

    return new WP_REST_Response(['success' => true], 200);
}

3. Безопасность: проверка подписи Webhook

Чтобы избежать подделки уведомлений, реализуйте проверку подписи. Обычно платёжные системы передают заголовок с подписью, например X-Signature. Добавим пример проверки:

function handle_payment_webhook(WP_REST_Request $request) {
    $secret = 'ваш_секретный_ключ';
    $signature = $request->get_header('X-Signature');
    $body = $request->get_body();

    if (!$signature || !hash_equals(hash_hmac('sha256', $body, $secret), $signature)) {
        return new WP_REST_Response(['error' => 'Invalid signature'], 403);
    }

    // Далее обработка, как в предыдущем примере
}

Проверка результата после внедрения

Для контроля корректной работы:

• Отправьте тестовый Webhook с платёжного шлюза и проверьте, что статус заказа в WooCommerce изменился.
• Проверьте логи сервера или плагина для отладки REST API (например, Query Monitor).
• Убедитесь, что при некорректных данных приходит корректный ответ с ошибкой.

Частые ошибки и как их исправить

• Ошибка 403 Forbidden при вызове Webhook – неправильная проверка подписи или отсутствует разрешение на endpoint. Проверьте permission_callback и подпись.
• Заказ не найден – неверный ID заказа в payload. Убедитесь, что платёжный шлюз передаёт правильный идентификатор.
• Статус не меняется – возможно, указан несуществующий статус. Используйте только поддерживаемые WooCommerce статусы: processing, completed, failed и т.д.
• Webhook не вызывается – проверьте доступность endpoint, настройки SSL и что URL прописан верно.

Практические советы по безопасности и производительности

• Всегда используйте проверку подписи Webhook, чтобы исключить посторонние запросы.
• Регистрируйте логи запросов Webhook для отладки и мониторинга.
• Ограничьте частоту вызовов endpoint с помощью rate limiting на уровне сервера.
• Обрабатывайте Webhook асинхронно через очередь, если требуется сложная логика, чтобы не задерживать ответ REST API.

Сравнение вариантов реализации автоматического обновления статусов