Webhooks автовыгрузок: уведомление о готовности файла

webhooksавтовыгрузки 26 окт 18:37 17

---

Уведомление вместо опроса

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

Теперь у каждой автовыгрузки есть вкладка «Webhooks»: после завершения выгрузки Q-Parser сам отправляет POST-запрос на ваш адрес. В теле — ссылки на файлы, номера парсинга и выгрузки, количество товаров, а в заголовках — подпись, по которой видно, что запрос отправил сервис. Подробная инструкция — в справке.

Как добавить webhook

1. Откройте автовыгрузку на странице «Автоматические выгрузки».
2. Перейдите на вкладку «Webhooks».
3. Добавьте адрес, на который нужно отправлять запрос, и нажмите «Сохранить».

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

Когда приходит запрос

После каждой завершённой выгрузки. Если парсинг завершился с ошибкой или был отменён, выгрузка не запускается, и webhooks не вызываются.

Ответ вашего сервера должен быть с кодом 2xx, тело ответа не важно. Если сервер ответил другим кодом, перенаправил запрос или не ответил за 10 секунд, Q-Parser повторит запрос через 1, 5, 10, 30 и 60 секунд. Если не удалась ни одна попытка, ошибка будет видна в настройках webhook — то есть молчаливого отказа не будет.

Что приходит в запросе

{
  "event": "automata.finished",
  "status": "success",
  "result": {
    "files": [
      "https://s3.q-parser.ru/a1b2c3d4/example.com.csv"
    ]
  },
  "automata_id": "0b6c1e3a-5f0d-4c6e-9a51-3d2f8f0c7e11",
  "automata_title": "Каталог example.com",
  "domain": "example.com",
  "format": "csv",
  "parsing_id": 123456,
  "export_id": "7d9e2b14-8a3f-4b6d-b1c2-5e4f3a2d1c0b",
  "goods_processed": 1520,
  "goods_exported": 1498,
  "created_at": 1767225600,
  "finished_at": 1767229200
}

• event — тип события, сейчас единственный: automata.finished;
• status — success или error, если выгрузка завершилась с ошибкой;
• result — результат выгрузки, как он показан в личном кабинете: files (ссылки на файлы), links (ссылки на отчеты), message (например, если выгрузка не запускалась из-за отсутствия изменений) и error (текст ошибки);
• automata_id, automata_title, domain, format — какая автовыгрузка сработала, с какого сайта и в каком формате;
• parsing_id, export_id — номера парсинга и выгрузки;
• goods_processed — сколько товаров обработано при парсинге, goods_exported — сколько выгружено;
• created_at, finished_at — время запуска парсинга и завершения выгрузки, Unix timestamp в секундах.

Подпись и повторные доставки

В запросе три служебных заголовка:

• X-QParser-Delivery — ID доставки, одинаковый во всех повторах;
• X-QParser-Timestamp — время отправки, Unix timestamp;
• X-QParser-Signature — подпись sha256=<HMAC-SHA256> от строки <X-QParser-Timestamp>.<тело запроса> с секретом webhook.

Подпись считается по сырому телу запроса, до разбора JSON. Пример на PHP:

<?php
$secret = 'секрет webhook из настроек автовыгрузки';
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_QPARSER_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_QPARSER_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature) || abs(time() - (int)$timestamp) > 300) {
    http_response_code(403);
    exit;
}

$data = json_decode($body, true);
// ... обработка $data
http_response_code(200);

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

Повтор приходит с тем же X-QParser-Delivery. Если обработчик уже видел этот ID, второй раз ничего делать не нужно — иначе повтор после таймаута превратится в двойной импорт. Окно по времени в примере (300 секунд) отсекает перехваченный старый запрос, отправленный повторно.

Зачем это нужно

• Импорт без опроса. Скрипт ждёт запрос и забирает файл по ссылке из result.files или по постоянной ссылке автовыгрузки — она не меняется между запусками. Вместо cron каждые 15 минут с проверкой «а файл уже новый?» — один вызов в момент, когда файл действительно готов.
• Несколько систем сразу. Файл нужен магазину, CRM и бухгалтерии: до 5 адресов на автовыгрузку, у каждого свой секрет и свой обработчик.
• Уведомление в свой чат. goods_processed и goods_exported приходят в теле: если товаров стало заметно меньше, это видно в момент выгрузки, а не через неделю.
• Ошибки выгрузки. status: error и текст в result.error — повод поднять алерт сразу, не заходя в кабинет.

Что учесть в своём обработчике

• Отвечайте быстро. Если обработка занимает больше 10 секунд, ставьте задачу в очередь и возвращайте 2xx, а работу делайте после: повтор через 10 секунд не поможет, если ваш сервер всё ещё занят.
• Редирект — не успех. Код 301 или 302 считается неудачной доставкой, поэтому адрес webhook должен отвечать сам, без переадресации на другой домен или на https.
• Файла может не быть. Если выгрузка не запускалась из-за отсутствия изменений, придёт message без ссылок — обработчик должен допускать пустой result.files, а не падать на нём.
• Событие, а не содержимое. Webhooks сообщают, что выгрузка завершилась, но файл они не передают: его скачивает ваш код.

Webhooks не заменяют автовыгрузку — они снимают с вашего кода необходимость угадывать момент, когда файл готов: расписание остаётся в Q-Parser, а сигнал о завершении приходит к вам. Настроить адреса можно на вкладке «Webhooks» у любой автовыгрузки, полное описание полей и подписи — в справке.

Попробовать на своих выгрузках: https://q-parser.ru/my