Веб-хуки

Интегрируйте Quote3D в ваш рабочий процесс с помощью уведомлений в реальном времени.

Что такое веб-хуки?

Веб-хуки позволяют вашему приложению получать уведомления в режиме реального времени о событиях, происходящих в Quote3D. Вместо опроса нашего API на предмет обновлений (например, проверки завершения расчёта стоимости), Quote3D будет отправлять HTTP POST-запрос по указанному вами URL сразу после возникновения события.

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

Доступные события

quote.completed: Запускается при успешном завершении расчета стоимости 3D-печати.
quote.failed: Запускается, если расчет стоимости не удался по какой-либо причине.
file.uploaded: Запускается при успешной загрузке нового файла модели на ваш аккаунт.
file.deleted: Запускается при удалении файла модели из вашего хранилища.
job.status_changed: Запускается на различных этапах асинхронной обработки задания.
widget.added_to_cart: Запускается, когда клиент добавляет модель в корзину, используя ваш встраиваемый виджет.

Пример полезной нагрузки

Все webhook-запросы отправляются в формате JSON. Вот пример полезной нагрузки события quote.completed:

{
  "event": "quote.completed",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "data": {
    "jobId": "job_01HXYZ123456789",
    "quoteId": "job_01HXYZ123456789",
    "status": "completed",
    "fileName": "gearbox-housing.stl",
    "fileId": "fl_987654321",
    "processingTimeMs": 22134,
    "result": {
      "quote_id": "job_01HXYZ123456789",
      "total_price": 25.5,
      "currency": "USD",
      "estimated_time": "2h 15m",
      "estimated_time_seconds": 8100,
      "filament_weight": 42.8,
      "printInfo": {
        "technology": "FDM",
        "material": "PLA",
        "color": "Black"
      }
    },
    "error": null
  }
}

Безопасность и верификация

Для обеспечения того, чтобы webhook-запросы исходили именно от Quote3D и не были подделаны, мы включаем HMAC-SHA256 подпись в заголовок X-Webhook-Signature.

При создании webhook в панели управления вам будет показан уникальный Секретный Ключ. Вам следует использовать этот ключ для верификации подписи каждого входящего запроса.

Этапы верификации:

Прочитайте тело запроса в необработанном виде как строку.
Извлеките подпись из заголовка X-Webhook-Signature и имя события из X-Webhook-Event.
Вычислите HMAC-SHA256 хеш необработанного тела, используя ваш Webhook Secret.
Вычислите хеш, добавьте префикс sha256= и сравните его с подписью. Если они совпадают, запрос подлинный.

const crypto = require('crypto');

// Secret Key from your Quote3D Dashboard
const SECRET = 'your_webhook_secret_here';

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const body = req.rawBody; // Keep the exact raw JSON string

  const hmac = crypto.createHmac('sha256', SECRET);
  const digest = 'sha256=' + hmac.update(body).digest('hex');

  if (typeof signature !== 'string' || typeof event !== 'string') {
    return false;
  }

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(digest, 'utf8');

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

Управление вебхуками

Вы можете управлять своими вебхуками непосредственно из Панели управления:

Перейдите на страницу Вебхуков в вашей панели управления.
Нажмите Создать вебхук, чтобы добавить новую конечную точку.
Введите URL вашей конечной точки (должен быть HTTPS) и выберите События, которые вы хотите отслеживать.
Немедленно скопируйте свой Секретный ключ и храните его в безопасном месте. Вы больше не сможете его увидеть!
При необходимости укажите ссылку на API Token, чтобы вебхук срабатывал только для действий, выполненных с этим токеном.

Повторная отправка неудачных доставок

Если целевой веб-хук был временно недоступен или вернул ошибку, вы можете просмотреть доставку в панели управления и запустить повторную отправку для этой конкретной записи доставки.

`POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend`

Эта конечная точка создает новую попытку доставки для существующей доставки веб-хука. Она полезна после того, как вы исправили принимающий сервер или хотите воспроизвести конкретное событие для отладки.

Используйте представление деталей веб-хука, чтобы определить ID доставки, которую вы хотите воспроизвести.
Вызовите конечную точку повторной отправки, указав ID веб-хука и ID доставки. API отвечает кодом 202 Accepted и создает новую ожидающую доставку.
Веб-хук должен быть по-прежнему активным и принадлежать аутентифицированному пользователю, иначе запрос на повторную отправку будет отклонен.