Используйте вебхуки для обычных изменений и сохраняйте запросы статуса для сверки своих записей с панелью. Пока нет надёжного публичного получателя, начните с пакетного опроса.
Заказ может завершиться во время перезапуска приложения. Событие может прийти дважды, если подтверждение потерялось. Отслеживание должно обрабатывать оба случая без устаревшей информации и двойного применения обновления.
Своя задача для каждого способа
- Опрос: получить текущую картину
- action=status возвращает состояние на момент проверки. Объединяйте до 100 ID в запросе. Короткий интервал увеличивает число запросов, даже когда ничего не меняется.
- Вебхуки: получать выбранные изменения
- NotPanel отправляет события на ваш HTTPS-адрес. Они не расходуют квоту запросов status клиента, но получателю нужны ресурсы и наблюдение.
- Сверка: восстановить пропуски
- После сбоя или при старой записи проверьте затронутые заказы. Событие можно пропустить, повторы ограничены, время получения не гарантируется.
Что отправляет API NotPanel
Руководство касается endpoint, созданных через webhook.add: публичный HTTPS URL и поддерживаемые события, включая order.processing, order.in_progress, order.completed, order.partial, order.refunded и order.refill_completed. Сохраните secret: webhook.list его не возвращает. Проверяйте состояние и ошибки через webhook.list, удаляйте регистрацию через webhook.remove.
Доставка API содержит массив events даже для одного события. У элемента есть id, event, timestamp и data; deliveryId определяет доставку. Сокращённый пример иллюстративный. Старые отметки времени не подходят для проверки временного допуска.
{
"events": [
{
"id": "EXAMPLE_EVENT_ID",
"event": "order.completed",
"timestamp": 1700000000,
"data": { "order": 7001, "status_key": "completed" }
}
],
"timestamp": 1700000001,
"deliveryId": "EXAMPLE_DELIVERY_ID"
}Читайте имя события из проверенного тела: пакетам API не нужен X-Webhook-Event. Вебхуки из dashboard используют другой формат с одним событием; эти форматы не взаимозаменяемы.
Проверьте подпись исходного тела и его временную метку.
Сохраните проверенную доставку до отправки ответа 2xx.
Применяйте событие один раз, а пропуски восстанавливайте запросами статуса.
Безопасный приём событий
- Сохраните исходное тело. Проверьте X-Webhook-Signature с secret и X-Webhook-Timestamp, затем примените свой временной допуск. Пересборка тела может изменить подписанные байты.
- Сравните X-Webhook-Delivery-Id с deliveryId подписанного тела. Сохраните доставку до ответа 2xx; если безопасно принять её нельзя, оставьте возможность повторной попытки.
- Обрабатывайте каждый events[].id один раз. Сохраняйте учёт повторов после перезапуска вместе с обновлением заказа. Событие может прийти через разные endpoint.
- Медленную работу выполняйте после приёма. Подпись подтверждает подлинность, не порядок. Если позднее событие противоречит новому состоянию, сначала запросите status.
Руководство по проверке подписи
Если получатель недоступен
Тайм-аут или ответ вне 2xx считается ошибкой. NotPanel повторяет доставку с увеличением пауз и приостанавливает API endpoint после 10 ошибок подряд; успех обнуляет счётчик. Следите за webhook.list: тишина не доказывает отсутствие изменений.
Периодически сверяйте нерешённые или старые заказы пакетами до 100 ID, соблюдая заголовки и лимиты. После ремонта приостановленного получателя убедитесь, что регистрация active. Не считайте, что все старые неудачные доставки автоматически повторятся.
Проверьте не только успешную доставку
Используйте искусственные сообщения и свой тестовый secret; реальные заказы не нужны.
- Две одинаковые доставки должны дать одно обновление.
- Одно событие в двух пакетах и перезапуск не должны дублировать обновление.
- Изменение байта или старое время должны отклоняться согласно вашей политике.
- После сбоя и позднего события status должен восстановить актуальную картину.
Выбор событий, проверка secret и быстрое подтверждение также описаны в рекомендациях GitHub по вебхукам. Заголовки, форматы и ограничения повторов здесь относятся к NotPanel.
Частые вопросы
Можно использовать только опрос?
Да. Объединяйте запросы и выбирайте интервал по объёму и лимитам. Вебхуки не обязательны для создания и отслеживания заказов.
Вебхук всегда приходит сразу и ровно один раз?
Нет. Возможны задержки и повторы. Проверяйте каждую доставку, применяйте событие один раз и сохраняйте сверку статуса для восстановления.
Какие заголовки проверять?
X-Webhook-Signature и X-Webhook-Timestamp. Затем сравните X-Webhook-Delivery-Id с deliveryId проверенного тела и обработайте массив events.
Защищает ли вебхук неопределённый add?
Это разные задачи. Повторяйте add с исходным request_id и неизменными параметрами, затем сохраняйте восстановленный ID заказа.
Справочники: контракт вебхуков · статус заказа · восстановление после тайм-аута.
