Вебхуки или опрос? Отслеживание заказов с восстановлением пропусков

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

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

Своя задача для каждого способа

Опрос: получить текущую картину

action=status возвращает состояние на момент проверки. Объединяйте до 100 ID в запросе. Короткий интервал увеличивает число запросов, даже когда ничего не меняется.

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

NotPanel отправляет события на ваш HTTPS-адрес. Они не расходуют квоту запросов status клиента, но получателю нужны ресурсы и наблюдение.

Сверка: восстановить пропуски

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

Что отправляет API NotPanel

Добавьте endpoint на странице API в dashboard или через webhook.add: публичный HTTPS URL и нужные события, например order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed и refill.rejected; полный список есть в справке по вебхукам. Сохраните secret: он показывается один раз, и webhook.list никогда его не возвращает. Просматривайте endpoint через webhook.list, отправляйте тестовый ping через webhook.test и удаляйте endpoint через webhook.remove.

Каждая доставка несёт одно событие в коротком конверте: id, type, schema_version, created_at, sequence и data. В data.order те же поля, что и в ответе action=status. Сокращённый пример ниже показывает структуру, а не реальный заказ.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Читайте тип события из проверенного тела. X-Webhook-Event тоже отправляется, но не подписан. Endpoint, добавленные в dashboard и через API, получают одинаковый конверт.

Безопасный приём событий

1. Сохраните исходное тело. Проверьте X-Webhook-Signature с secret и X-Webhook-Timestamp, затем примените свой временной допуск. Пересборка тела может изменить подписанные байты.
2. Записывайте X-Webhook-Delivery-Id в журнал, чтобы отслеживать попытки: он не меняется при повторах этой доставки. Сохраните проверенное событие до ответа 2xx; если безопасно принять его нельзя, оставьте возможность повторной попытки.
3. Обрабатывайте каждый id события один раз. Сохраняйте учёт повторов после перезапуска вместе с обновлением заказа. Один и тот же id события приходит на каждый endpoint, подписанный на это событие.
4. Медленную работу выполняйте после приёма. Подпись подтверждает подлинность, не порядок. Упорядочивайте события по sequence, а если позднее событие противоречит новому состоянию, сначала запросите status.

Руководство по проверке подписи

Если получатель недоступен

Тайм-аут (10 секунд) или ответ вне 2xx — неудачная попытка. NotPanel пытается доставить событие до 8 раз за 24 часа: сразу, затем через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов, 12 часов и 24 часа после события. После 50 ошибок подряд или 3 дней без единого успеха endpoint приостанавливается, а владелец аккаунта получает уведомление. Успешная доставка обнуляет счётчик. Следите за webhook.list: тишина не доказывает отсутствие изменений.

Периодически сверяйте нерешённые или старые заказы пакетами до 100 ID, соблюдая заголовки и лимиты. После ремонта возобновите endpoint в разделе вебхуков на странице API в dashboard — это обнуляет счётчик ошибок. Можно также удалить его через webhook.remove, снова добавить исправленный HTTPS URL и нужные события через webhook.add, безопасно сохранить новый secret и обновить проверку на получателе. В публичном API нет действия для возобновления endpoint. Доставки, стоявшие в очереди на момент паузы, не повторяются, поэтому сверьте пропущенные состояния заказов через status.

Проверьте не только успешную доставку

Используйте искусственные сообщения и свой тестовый secret; реальные заказы не нужны.

• Две одинаковые доставки должны дать одно обновление.
• Одно и то же событие, доставленное дважды с перезапуском между доставками, должно распознаваться как уже обработанное.
• Изменение байта или старое время должны отклоняться согласно вашей политике.
• После сбоя и позднего события status должен восстановить актуальную картину.

Выбор событий, проверка secret и быстрое подтверждение также описаны в рекомендациях GitHub по вебхукам. Заголовки, форматы и ограничения повторов здесь относятся к NotPanel.

Частые вопросы

Можно использовать только опрос?

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

Вебхук всегда приходит сразу и ровно один раз?

Нет. Возможны задержки и повторы. Проверяйте каждую доставку, применяйте событие один раз и сохраняйте сверку статуса для восстановления.

Какие заголовки проверять?

X-Webhook-Signature и X-Webhook-Timestamp; затем прочитайте id, type и data из проверенного тела. X-Webhook-Delivery-Id используйте только для отслеживания попыток.

Защищает ли вебхук неопределённый add?

Это разные задачи. Повторяйте add с исходным request_id и неизменными параметрами, затем сохраняйте восстановленный ID заказа.

Справочники: контракт вебхуков · статус заказа · восстановление после тайм-аута.