Webhook vs API: что выбрать для интеграции сайта с внешним сервисом

Webhook vs API — два способа связать сайт с CRM, платёжной системой или другим сервисом. Правильный выбор помогает автоматизировать процессы, ускорить обмен данными и сократить расходы на разработку. Разберём, как работают эти технологии, чем они отличаются и какой вариант подойдёт вашему проекту. Вы узнаете, когда использовать API, когда подключать webhook и как избежать типичных ошибок интеграции.

Webhook vs API: в чём разница

Представим интернет-магазин на WordPress. Клиент оформляет заказ, оплачивает покупку и ждёт подтверждения. Магазину нужно передать данные в CRM, обновить статус заказа и отправить уведомление менеджеру.

Для решения этой задачи можно использовать API или webhook. Оба механизма обеспечивают обмен данными, но работают по-разному.

API (Application Programming Interface) — программный интерфейс для взаимодействия систем. Одна программа отправляет запрос другой и получает ответ. Например, сайт обращается к CRM, чтобы создать карточку клиента.

Webhook — механизм уведомления о событии. Когда происходит определённое действие, сервис самостоятельно отправляет HTTP-запрос на заранее указанный адрес. Например, платёжная система сообщает сайту об успешной оплате.

Главное отличие заключается в инициативе обмена данными:

• API: ваш сайт обращается к внешнему сервису, когда ему нужны данные или действие.
• Webhook: внешний сервис уведомляет ваш сайт, когда происходит событие.
• API обычно подходит для запросов по требованию.
• Webhook помогает оперативно реагировать на изменения без постоянных проверок.

При этом webhook часто использует HTTP и может передавать JSON. По сути, он тоже опирается на сетевые интерфейсы и договорённости между системами. Поэтому API и webhook не исключают друг друга.

Как работает API при интеграции сайта

API позволяет сайту обращаться к внешнему сервису по определённым правилам. Эти правила описывают доступные методы, параметры запросов, формат ответов и требования к авторизации.

Допустим, менеджер открывает страницу заказа. Сайт должен показать актуальный статус доставки из логистической системы.

Последовательность действий выглядит так:

1. Сайт формирует HTTP-запрос к API.
2. Внешний сервис проверяет права доступа.
3. Сервис обрабатывает запрос и возвращает данные.
4. Сайт получает ответ и показывает результат пользователю.

Например, запрос может выглядеть так:

GET /api/orders/12345 HTTP/1.1
Host: example.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Сервис может вернуть следующий JSON:

{
  "order_id": 12345,
  "status": "shipped",
  "tracking_number": "TRK123456"
}

Сайт использует ответ, чтобы показать клиенту номер отправления и статус заказа.

Когда API особенно полезен

API подходит для сценариев, в которых инициатору нужны данные или конкретное действие.

Например:

• получение списка товаров из каталога поставщика;
• проверка доступности товара перед оформлением заказа;
• расчёт стоимости доставки;
• загрузка истории заказов из CRM;
• создание клиента или сделки по команде менеджера;
• получение курсов валют или других актуальных данных.

API также помогает управлять процессами из административной панели. Менеджер нажимает кнопку, сайт отправляет запрос и показывает результат.

Однако разработчику необходимо учитывать ограничения внешнего сервиса. API может ограничивать частоту запросов, требовать токены доступа или возвращать ошибки при высокой нагрузке.

Если сайт постоянно запрашивает одни и те же данные, стоит предусмотреть кеширование. Это снизит количество обращений и ускорит загрузку страниц.

Как работает webhook

Webhook работает по принципу уведомления о событии. Владелец сайта настраивает адрес обработчика, а внешний сервис отправляет туда запрос при наступлении определённого события.

Рассмотрим интернет-магазин с онлайн-оплатой.

1. Клиент оплачивает заказ.
2. Платёжная система подтверждает операцию.
3. Система отправляет webhook на адрес сайта.
4. Сайт проверяет подлинность уведомления.
5. Обработчик обновляет заказ и запускает дальнейшие действия.

Например, сервис отправляет такой запрос:

POST /webhooks/payment HTTP/1.1
Host: shop.example.com
Content-Type: application/json

Тело запроса может содержать следующие данные:

{
  "event": "payment.succeeded",
  "payment_id": "pay_98765",
  "order_id": 12345,
  "amount": 4990,
  "currency": "RUB"
}

Это условный пример. Реальные названия полей и формат подписи зависят от платёжного провайдера.

После проверки уведомления сайт может изменить статус заказа, отправить письмо покупателю и передать информацию в CRM.

Когда webhook особенно полезен

Webhook подходит для событий, о которых важно узнать без постоянного опроса сервиса.

Типичные сценарии:

• успешная или неуспешная оплата;
• создание нового лида в CRM;
• изменение статуса доставки;
• оформление или отмена заказа;
• отправка формы обратной связи;
• изменение подписки пользователя;
• завершение фоновой задачи во внешнем сервисе.

Допустим, сайт проверяет статус оплаты каждые 30 секунд. За час это может составить до 120 запросов на один заказ. Webhook позволяет получать уведомление по событию и уменьшает необходимость в таких проверках.

При этом webhook не гарантирует мгновенную доставку во всех случаях. Сервис может повторить отправку, задержать уведомление или временно не доставить его из-за ошибки сети.

Поэтому обработчик должен поддерживать повторные запросы и корректно работать с задержками.

Сравнение API и webhook: таблица отличий

Выбор зависит от задачи, требований к актуальности данных и возможностей внешнего сервиса.

Критерий	API	Webhook
Инициатор	Ваш сайт или приложение	Внешний сервис
Принцип работы	Запрос и ответ	Уведомление о событии
Когда передаются данные	По запросу	При наступлении события
Получение текущего состояния	Да, если API предоставляет нужные данные	Не всегда, зависит от событий
Постоянная проверка изменений	Может потребоваться	Обычно не нужна
Основные расходы	Запросы, обработка, ограничения API	Приём, проверка и обработка уведомлений
Типичные задачи	Получение данных, запуск действий	Реакция на события
Основные риски	Тайм-ауты, ограничения запросов, ошибки ответа	Повторы, задержки, дубликаты, нарушение порядка событий

Важно понимать: API не всегда работает синхронно, а webhook не всегда доставляется один раз. Например, API может запускать асинхронную задачу, а webhook-сервис может повторять уведомление после тайм-аута.

Поэтому при проектировании интеграции нужно учитывать не только способ передачи данных, но и гарантии конкретного поставщика.

Что выбрать для сайта на WordPress

В WordPress можно использовать оба подхода. Решение зависит от того, какие данные нужно передавать и кто должен инициировать обмен.

Интеграция через API

Предположим, компании нужно синхронизировать каталог товаров с поставщиком. Сайт должен получать названия, цены, остатки и описания.

Разработчик настраивает запросы к API поставщика. Синхронизация запускается по расписанию или вручную. Затем сайт обновляет карточки товаров.

Для этого сценария API удобен, поскольку позволяет запросить нужный набор данных и обработать ответ.

В WordPress можно использовать HTTP API:

$response = wp_remote_get(
    'https://api.example.com/products',
    array(
        'timeout' => 10,
        'headers' => array(
            'Authorization' => 'Bearer ' . $api_token,
            'Accept'        => 'application/json',
        ),
    )
);

if (is_wp_error($response)) {
    error_log('Ошибка API: ' . $response->get_error_message());
    return;
}

$status_code = wp_remote_retrieve_response_code($response);
$body        = wp_remote_retrieve_body($response);

if ($status_code < 200 || $status_code >= 300) {
    error_log('API вернул HTTP ' . $status_code);
    return;
}

$data = json_decode($body, true);

if (!is_array($data)) {
    error_log('API вернул некорректный JSON');
    return;
}

// Здесь можно обработать и сохранить полученные товары.

Это пример основы HTTP-запроса. В рабочем проекте нужно добавить проверку структуры данных, кеширование, обработку ограничений API и безопасное хранение токена.

Не размещайте секретные ключи непосредственно в публичном коде темы или репозитории.

Интеграция через webhook

Теперь представим другой сценарий. Покупатель оплачивает заказ, и сайт должен получить уведомление от платёжной системы.

В WordPress можно зарегистрировать собственный REST API endpoint. Внешний сервис будет отправлять уведомления на его адрес.

Пример регистрации обработчика:

add_action('rest_api_init', function () {
    register_rest_route('computy/v1', '/payment-webhook', array(
        'methods'             => 'POST',
        'callback'            => 'computy_handle_payment_webhook',
        'permission_callback' => '__return_true',
    ));
});

function computy_handle_payment_webhook(WP_REST_Request $request) {
    $payload = $request->get_json_params();

    if (!is_array($payload)) {
        return new WP_Error(
            'invalid_payload',
            'Некорректный формат данных',
            array('status' => 400)
        );
    }

    // До изменения заказа необходимо проверить подпись
    // и защититься от повторной обработки события.

    return new WP_REST_Response(
        array('received' => true),
        200
    );
}

После регистрации адрес обработчика будет выглядеть так:

https://example.com/wp-json/computy/v1/payment-webhook

Важно: этот код демонстрирует регистрацию endpoint, но не готов к приёму реальных платежных уведомлений. В рабочей системе нельзя изменять заказ до проверки подписи, идентификатора события и его соответствия ожидаемому платежу. Метод __return_true сам по себе не обеспечивает защиту.

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

Можно ли использовать API и webhook вместе

Да. Во многих проектах совместная работа этих механизмов даёт наиболее надёжный результат.

Рассмотрим интеграцию интернет-магазина с CRM и платёжной системой.

Сначала клиент оформляет заказ. Сайт передаёт сведения о нём в CRM через API. После оплаты платёжная система отправляет webhook. Сайт проверяет событие и обновляет статус заказа.

Затем обработчик может обратиться к API платёжного провайдера. Это нужно, например, чтобы сверить сумму и окончательный статус операции.

Схема взаимодействия выглядит так:

1. API: сайт создаёт заказ или сделку.
2. Webhook: внешний сервис сообщает об изменении.
3. Проверка: сайт подтверждает подлинность уведомления.
4. API: при необходимости сайт запрашивает актуальные сведения.
5. Обработка: система обновляет данные и запускает бизнес-процесс.

Такой подход позволяет оперативно реагировать на события и проверять важные данные через API.

Он особенно полезен для интернет-магазинов, CRM, систем бронирования и сервисов подписки.

Безопасность интеграции: что важно предусмотреть

Ошибки интеграции могут привести к потере данных, повторным операциям и утечке конфиденциальной информации. Поэтому безопасность нужно закладывать на этапе проектирования.

1. Проверяйте подлинность запросов

Для API используйте предусмотренную сервисом авторизацию. Это могут быть токены, OAuth 2.0 или другие механизмы.

Для webhook проверяйте цифровую подпись, если её поддерживает поставщик. Обычно подпись вычисляют по исходному телу запроса и секретному ключу.

Не считайте наличие HTTPS достаточным подтверждением подлинности отправителя. HTTPS защищает передачу данных, но не заменяет проверку подписи.

2. Защищайтесь от повторной обработки

Внешний сервис может повторно отправить уведомление, если не получил ответ вовремя. Например, сайт уже обновил заказ, но соединение прервалось до отправки подтверждения.

Используйте идентификатор события и сохраняйте сведения об обработанных уведомлениях. Повторный запрос не должен повторно списывать деньги или создавать дубликаты сделок.

Такой подход называется идемпотентностью.

3. Обрабатывайте ошибки и повторы

Внешний сервис может временно стать недоступным. Поэтому интеграции нужны тайм-ауты, журнал ошибок и контролируемые повторные попытки.

Для webhook полезно быстро подтвердить получение события, а тяжёлую обработку перенести в фоновую задачу. Но подтверждать успешную обработку следует только в соответствии с требованиями провайдера.

4. Не доверяйте входящим данным

Проверяйте структуру JSON, типы полей, допустимые значения и права на изменение конкретного заказа.

Не используйте полученные данные напрямую в SQL-запросах или HTML. Применяйте подходящие средства WordPress для проверки, экранирования и безопасного сохранения данных.

5. Следите за журналами интеграции

Логи помогают определить, почему заказ не обновился или CRM не получила заявку.

Записывайте идентификатор события, время, результат обработки и код ошибки. Не сохраняйте в открытых логах пароли, секретные ключи и полные платёжные данные.

Типичные ошибки при выборе способа интеграции

Даже правильно выбранная технология не гарантирует стабильную работу. Часто проблемы возникают из-за неверных ожиданий.

Ошибка 1. Использовать API для постоянного опроса без необходимости.

Сайт регулярно запрашивает статус каждого заказа. Это увеличивает нагрузку и расходует лимиты запросов.

Решение: если сервис поддерживает webhook, используйте его для уведомлений. API оставьте для проверки состояния и получения подробностей.

Ошибка 2. Полагаться только на webhook.

Уведомление может задержаться или не дойти. Кроме того, события иногда приходят не по порядку.

Решение: предусмотрите повторную обработку и периодическую сверку критически важных данных через API.

Ошибка 3. Считать ответ HTTP 200 доказательством завершённой операции.

Успешный HTTP-ответ подтверждает определённый результат запроса, но сам по себе не доказывает оплату заказа.

Решение: проверяйте подпись, идентификатор платежа, сумму, валюту и допустимый переход статуса.

Ошибка 4. Передавать данные без контроля доступа.

Открытый обработчик webhook может стать точкой входа для поддельных запросов.

Решение: используйте подписи, проверку входных данных, ограничение прав и защиту от повторов.

Ошибка 5. Не учитывать ограничения внешнего сервиса.

API может ограничивать число запросов, а webhook — количество повторных отправок и время ожидания ответа.

Решение: изучите документацию провайдера до начала разработки. Уточните форматы событий, правила авторизации, лимиты и условия повторной доставки.

Как выбрать подходящий вариант: чек-лист

Перед разработкой интеграции ответьте на несколько вопросов.

• Нужно ли сайту самостоятельно запрашивать данные?
• Должна ли внешняя система уведомлять сайт о событиях?
• Требуется ли получить актуальное состояние объекта в любой момент?
• Поддерживает ли сервис webhook и предоставляет ли документацию?
• Есть ли ограничения на количество API-запросов?
• Как система обработает повторное или задержанное событие?
• Как вы будете проверять подписи и хранить секретные ключи?
• Нужны ли журналирование, мониторинг и повторная обработка ошибок?

Если сайт должен получать данные по запросу, начните с API. Если требуется реагировать на события, рассмотрите webhook. Если важны и оперативные уведомления, и проверка данных, объедините оба механизма.

Заключение

Webhook vs API — это не выбор между двумя взаимоисключающими технологиями. API помогает запрашивать данные и управлять внешними сервисами. Webhook сообщает сайту о событиях и сокращает необходимость постоянного опроса.

Для WordPress и WooCommerce выбор зависит от бизнес-процесса, требований безопасности и возможностей стороннего сервиса. При этом надёжная интеграция требует не только правильного способа обмена данными. Важны проверка запросов, защита от дубликатов, обработка ошибок и контроль состояния операций.

Если вам нужно связать сайт с CRM, платёжной системой, складом или другим внешним сервисом, специалисты веб-студии «Компьюти» помогут выбрать архитектуру интеграции. Мы изучим ваши задачи, подготовим техническое решение и разработаем механизм обмена данными с учётом требований безопасности и дальнейшего развития проекта.

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