Перейти к основному содержимому

Вебхуки

Укажите URL и секрет вебхука в настройках интеграции в дашборде и включите доставку. Cloud API использует один адрес для всех событий. История доставки доступна в дашборде. Секрет вебхука отличается от API-ключа.

Вебхуки отправляются с сервера с IP-адресом 199.89.134.2.

Формат​

События приходят HTTP POST с Content-Type: application/json и X-Webhook-Signature:

{
"event": "order.completed",
"timestamp": "2026-09-28T12:00:00.000Z",
"data": {
"order_id": 401,
"status": "completed",
"amount_usd": "5.0000",
"currency": "USD",
"vm_id": 101,
"rental_id": null,
"error_code": null,
"error_message": null,
"order_type": "vm_purchase",
"api_user_id": "customer-123"
}
}

event — тип события, timestamp — время создания конверта в UTC. data зависит от события. События ресурсов также содержат data.event_id (строка UUID для почты, число для ресурсов хостинга) и data.created_at исходного события; у событий заказов этих двух полей нет. Некоторые поля необязательны и отсутствуют, если их не было в исходном событии.

События заказов​

СобытиеЗначение
order.completedДействие завершено; покупка дедика зарезервирована, но ещё не выдана
order.failedОшибка заказа; проверьте причину и транзакции
order.refundedСумма возвращена на баланс интеграции
order.reviewНеопределённый или частичный результат, требующий выяснения

Все четыре используют поля примера выше: order_id, order_type, api_user_id, status, amount_usd, currency, допускающие null vm_id, rental_id, error_code, error_message. vm_id возвращается только для завершённого заказа. ipv4_renewal дополнительно содержит ip_id и paid_until. Завершённая покупка VPS может содержать guest_initialization; если результата нет, значение — null.

Типы заказов: vm_purchase, vm_renewal, vm_resize, traffic_purchase, ipv4_purchase, ipv4_renewal, dedicated_purchase, dedicated_renewal, backup_purchase, backup_renewal, backup_service_delete, backup_delete, backup_restore, backup_export, mail_purchase, mail_renewal, mail_upgrade, mail_delete. У заказов управления бекапами сумма нулевая. В ответе также есть допускающие null backup_service_id, backup_id и worker_operation_id. При возврате передаётся исходная положительная сумма заказа; отличайте возврат от покупки по event/status.

События VPS​

order.completed для покупки VPS также содержит nullable-поле application: публичные сведения о приложении и installer_sha256, без содержимого установщика и реквизитов доступа. vm.created и vm.reinstalled включают это же поле для соответствующей установки; null означает отсутствие приложения. Явный cloud-init при переустановке заменяет прежнее приложение.

При application.installation_mode=background выдача и оплачиваемый период начинаются во время установки приложения. guest_initialization.status=succeeded не подтверждает его готовность; отдельного вебхука завершения установки нет. Подробнее — приложения.

Общие поля: event_id, created_at, vm_id; при наличии — api_user_id, order_id, operation_id. В таблице перечислены дополнительные поля. Создание содержит ips с объектами только из address. Удаление содержит held_ips по формату результата удаления VPS. События ошибок включают публичные error_code и error_message.

СобытиеЗначениеДополнительные поля data
vm.rescue.enabledRescue включёнstatus, rescue
vm.rescue.enable_failedОшибка включения Rescuerequires_review, error_code, error_message
vm.rescue.disabledЗагрузка обычной ОС восстановленаstatus, rescue
vm.rescue.disable_failedОшибка выхода из Rescuerequires_review, error_code, error_message
vm.reinstalledОС переустановленаos, hostname, wipe_extra_disks, status, guest_initialization
vm.reinstall_failedОшибка переустановки ОСrequires_review, error_code, error_message
vm.password.changedПароль изменёнlogin, password_changed, status
vm.password.change_failedОшибка смены пароляrequires_review, error_code, error_message
vm.createdVPS созданstatus, hostname, smtp_blocked, paid_until, ips, guest_initialization
vm.creation_failedОшибка создания VPSstatus, requires_review, error_code, error_message
vm.creation_cancelledСоздание отменено в очереди до резервированияstatus="cancelled", requires_review=false; vm_id=null
vm.resizedРесурсы тарифа измененыstatus, cpu_cores, cpu_percent, ram_mb, disk_gb, traffic_limit_bytes, resources_applied, traffic_applied
vm.resize_failedОшибка либо частичное применение тарифаrequires_review, status, cpu_cores, cpu_percent, ram_mb, disk_gb, traffic_limit_bytes, resources_applied, traffic_applied, error_code, error_message
vm.renewedVPS продлёнpaid_until, resume_pending, auto_start
vm.traffic.topped_upТрафик докупленperiod_id, quota_revision, additional_bytes, total_additional_bytes, remaining_bytes
vm.traffic.updatedКвота трафика измененаperiod_id, quota_revision, previous_limit_bytes, traffic_limit_bytes, remaining_bytes
vm.ip.attachedIPv4 назначенstatus, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required
vm.ip.attach_failedОшибка назначения IPv4requires_review, error_code, error_message
vm.ip.replacedПолучен результат замены IPstatus, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required
vm.ip.replace_failedОшибка замены IPrequires_review, error_code, error_message
vm.ip.detachedIPv4 снятstatus, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required
vm.ip.detach_failedОшибка снятия IPv4requires_review, error_code, error_message
vm.power.changedКоманда питания выполненаaction, status, uptime
vm.power.failedОшибка команды питанияaction, requires_review, error_code, error_message
vm.deletedVPS удалёнstatus, keep_ips, reason, paid_until, held_ips
vm.delete_failedОшибка удаления VPSrequires_review, error_code, error_message
vm.expiringСкоро окончание оплатыpaid_until, hours_before, delete_after
vm.deleting_soonЗа час до удаления VPSpaid_until, hours_before, delete_after, reason
vm.suspendedVPS приостановленstatus, reason, paid_until, delete_after
vm.resumedVPS восстановленstatus, reason, paid_until, auto_started
vm.traffic.lowТрафик заканчиваетсяperiod_id, quota_revision, starts_at, ends_at, included_bytes, additional_bytes, outgoing_bytes, overage_bytes, remaining_bytes
vm.traffic.exhaustedТрафик исчерпанperiod_id, quota_revision, starts_at, ends_at, included_bytes, additional_bytes, outgoing_bytes, overage_bytes, remaining_bytes
vm.shaping.changedОграничение скорости измененоprevious_reason, reason, limit_mbps, bandwidth_limited_until, manual_limited_until

Административная блокировка​

СобытиеЗначениеДополнительные поля data
vm.blockedЗапрет действует, выключение подтвержденоoperation_id, status, admin_blocked_at, admin_block_reason
vm.block_failedВыполнение блокировки не завершилось; запрет сохраняетсяoperation_id, requires_review, error_code, error_message, admin_blocked_at, admin_block_reason
vm.unblockedЗапрет снят, VPS остаётся выключеннымoperation_id, status, admin_blocked_at: null, admin_block_reason: null
vm.unblock_failedСнятие блока не завершилось; запрет сохраняетсяoperation_id, requires_review, error_code, error_message, admin_blocked_at, admin_block_reason

Передаются общие поля событий VPS. События получает интеграция-владелец, в том числе при действии администратора. vm.block_failed не подтверждает выключение. Устраняйте повторы по event_id; при запоздалом событии перечитайте GET /vms/{vm_id} перед обновлением отображаемого состояния. Не запускайте VPS автоматически после продления или снятия блока. Подробнее: административная блокировка.

Результат инициализации и Rescue​

vm.created, vm.reinstalled и завершённый заказ покупки VPS передают guest_initialization отдельно от результата создания ресурса:

{
"guest_initialization": {
"status": "failed",
"error_code": "cloud_init_failed"
}
}

Возможные статусы: succeeded с error_code=null, failed с cloud_init_failed или unknown с guest_initialization_timeout после 15 минут ожидания. Пользовательская инициализация может завершиться с ошибкой или остаться неподтверждённой, а работающий VPS — сохраниться с завершённой покупкой. Это не ошибка создания и не автоматический возврат оплаты. В событии ресурса поле отсутствует, если результата нет.

Успешные события Rescue содержат вложенное состояние:

{
"event": "vm.rescue.enabled",
"timestamp": "2026-09-28T12:00:00.000Z",
"data": {
"event_id": 701,
"created_at": "2026-09-28T12:00:00Z",
"vm_id": 101,
"api_user_id": "customer-123",
"operation_id": 501,
"status": "running",
"rescue": {
"active": true,
"access": "ssh",
"requires_review": false,
"operation_id": 501,
"operation_status": "succeeded"
}
}
}

При выходе rescue.active=false; VPS может остаться stopped, если срок оплаты истёк или он приостановлен. active означает сохранённый контекст Rescue, а не гарантию доступности SSH. access принимает ssh, console или null. События ошибок передают requires_review, error_code и error_message; актуальное состояние смотрите в деталях VPS и операции.

Пароли, содержимое cloud-init, stdout и stderr в этих вебхуках не передаются. Правила запросов описаны в разделе Cloud-init и Rescue.

События IPv4​

Общие поля при наличии: event_id, created_at, ip_id, address, family, vm_id, api_user_id, paid_until. У сохранённого адреса vm_id=null. Дополнительные поля:

СобытиеЗначениеДополнительные поля data
ip.allocatedIPv4 выделен без VPSoperation_id, order_id, location_id; vm_id=null
ip.expiringСрок оплаты IPv4 заканчиваетсяhours_before, delete_after
ip.releasing_soonЗа час до освобождения IPv4hours_before, delete_after, reason
ip.suspendedIPv4 приостановленreason, delete_after
ip.resumedIPv4 восстановленreason
ip.releasedIPv4 освобождёнreason

События аренды дедиков​

Общие поля при наличии: event_id, created_at, rental_id, plan_id, order_id, api_user_id, status, issued_at, paid_until, overdue_at, finished_at. Доступы не передаются вебхуком: получите детали аренды после dedicated.issued. Дополнительные поля:

СобытиеЗначениеДополнительные поля data
dedicated.preparingАренда зарезервирована и готовится—
dedicated.issuedВыделенный сервер выдан—
dedicated.expiringОплата аренды заканчиваетсяhours_before
dedicated.overdueОплата аренды истеклаrelease_after
dedicated.releasing_soonЗа час до освобождения арендыhours_before, release_after, reason
dedicated.renewedАренда продлена—
dedicated.releasedАренда освобождена или отменена; проверьте reasonreason
dedicated.completedОчистка аренды завершена—
dedicated.power_changedКоманда питания завершенаpower_state, changed, необязательный power_action
dedicated.power_failedОшибка команды питанияerror_code, error_message, requires_review
dedicated.reinstalledОС переустановленаos, verified
dedicated.reinstall_failedОшибка переустановки ОСerror_code, error_message, requires_review

Эти четыре события питания/переустановки также содержат operation_id, action (dedicated_power или dedicated_reinstall) и rental_order_id — исходный заказ покупки аренды. Их order_id относится к отдельному финансовому заказу команды и равен null для этих публичных маршрутов управления. status — статус аренды; результат команды определяйте по событию или операции. verified подтверждает проверки установки, а не работу приложений клиента. Пароли, SSH-ключи и внутренние реквизиты управления исключены. После dedicated.reinstalled получите новые доступы в деталях аренды.

События бекапов​

Общие поля при наличии: event_id, created_at, backup_service_id, backup_id, source_vm_id, vm_id, api_user_id, order_id, operation_id, kind, service_type, paid_until, delete_after. source_vm_id — исходная VPS; услуга хранения может существовать после её удаления. У ежедневных автоматических копий заказа может не быть.

СобытиеЗначениеДополнительные поля
backup_service.createdУслуга хранения активирована—
backup_service.creation_failedПервая копия не созданаerror_code, error_message
backup_service.renewedХранение продленоpaid_until, delete_after
backup_service.expiringПредупреждение за 24 часа до окончания оплатыpaid_until, delete_after
backup_service.expiredОплата хранения закончиласьpaid_until, delete_after
backup_service.deleting_soonПредупреждение за час до удаленияpaid_until, delete_after
backup_service.deletedУслуга и её копии удалены—
backup_service.deletion_failedОшибка удаления услугиerror_code, error_message
backup.createdКопия созданаstored_size_bytes, logical_size_bytes
backup.creation_failedОшибка создания копииerror_code, error_message
backup.deletedКопия удалена—
backup.deletion_failedОшибка удаления копииerror_code, error_message
backup.restoredИсходная VPS восстановленаtarget_vm_id, restore_mode="existing"
backup.restore_failedОшибка восстановленияtarget_vm_id, restore_mode, error_code, error_message
backup.export_readyАрхив готов к скачиваниюsize_bytes, expires_at
backup.export_failedОшибка подготовки архиваerror_code, error_message

Первую оплату или продление подтверждает order.completed. У ожидающего ручного заказа сумма нулевая до измерения копии. Если средств недостаточно, Cloud API удаляет неоплаченную копию и отправляет order.failed с backup_insufficient_balance; начальные события успешного создания для этой неуспешной покупки не пересылаются. Статусы хранения и операции описывают выполнение отдельно от оплаты.

При включённом автопродлении backup_service.expiring и backup_service.deleting_soon запускают попытки продления. Предупреждения пересылаются и при отключённом автопродлении или нехватке средств. После окончания оплаты есть 24 часа до удаления; после предупреждения проверяйте актуальный срок или результат продления. Поля hours_before у предупреждений бекапов нет.

Ключи шифрования, пароли, идентификаторы инфраструктуры и подписанные ссылки не передаются. Ошибки имеют код backup_operation_failed и публичное сообщение. Ссылку получайте через авторизованный маршрут скачивания. Создание новой VPS из копии использует обычные события vm.created и vm.creation_failed.

Значения полей и последние предупреждения​

  • Даты (created_at, paid_until, starts_at, ends_at, delete_after, release_after, bandwidth_limited_until, manual_limited_until) передаются в UTC; необязательные даты могут быть null. Счётчики байт — целые числа. limit_mbps — ограничение скорости в Мбит/с либо null.
  • Причины шейпинга: traffic (исчерпана квота), bandwidth (длительная нагрузка), manual (лимит администратора) или null (нет ограничения). В каждом направлении действует меньший из активных лимитов. manual_limited_until: null означает отсутствие срока, если ручной лимит включён. Изменять ручной лимит администратора через публичный API нельзя.
  • status описывает ресурс, а не доставку. reason — причина перехода, например payment_expired. Не используйте одну причину как идентификатор события.
  • hours_before — интервал предупреждения. delete_after — дедлайн удаления VPS/освобождения IPv4, release_after — дедлайн аренды дедика.
  • resources_applied / traffic_applied показывают применённые части смены тарифа. requires_review=true означает, что результат требует выяснения перед новой командой.
  • period_id и quota_revision определяют период трафика и ревизию квоты. additional_bytes — добавленный/текущий объём в зависимости от события, total_additional_bytes — общий объём после докупки. remaining_bytes — оставшаяся квота.
  • guest_configuration_required=true означает, что нужно проверить сеть внутри ОС клиента. addresses содержит итоговые адреса; keep_ip/keep_ips — выбор сохранения. Итоговое состояние уточняйте в деталях VPS/IP.
  • resume_pending, auto_start и auto_started описывают восстановление после оплаты. Успешное продление не обязательно означает, что VPS уже запущен.

vm.deleting_soon, ip.releasing_soon и dedicated.releasing_soon предупреждают за час до удаления/освобождения после 24 часов ожидания оплаты. Они передаются и при выключенном автопродлении либо недостаточном балансе. При включённом автопродлении Cloud API делает последнюю попытку оплаты. Предупреждение всё равно содержит исходный дедлайн; результат смотрите по событиям продления или состоянию ресурса.

Пример последнего предупреждения VPS:

{
"event": "vm.deleting_soon",
"timestamp": "2026-09-29T11:00:00.000Z",
"data": {
"event_id": 701,
"created_at": "2026-09-29T11:00:00+00:00",
"vm_id": 101,
"api_user_id": "customer-123",
"paid_until": "2026-09-28T12:00:00+00:00",
"hours_before": 1,
"delete_after": "2026-09-29T12:00:00+00:00",
"reason": "payment_expired"
}
}

Проверка подписи​

X-Webhook-Signature — HMAC-SHA256 от точных исходных байт тела запроса, в виде hex-строки нижнего регистра, с секретом вебхука интеграции. Сам секрет не передаётся. Проверяйте исходные байты до разбора JSON; повторная сериализация меняет данные подписи.

const crypto = require('node:crypto');

function verifySignature(rawBody, secret, signature) {
if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/.test(signature)) {
return false;
}

const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest();

return crypto.timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

rawBody должен быть исходным Buffer вашего HTTP-сервера до JSON-middleware.

Подтверждение, повторы и доставка​

  1. Проверьте подпись и сохраните событие.
  2. Примените его один раз: для ресурсов используйте интеграцию и data.event_id; для результатов заказов — интеграцию, data.order_id и event.
  3. После приёма верните HTTP 200 или 201. Тело ответа не требуется. Другие коды, включая 202 и 204, не подтверждают доставку.

Таймаут HTTP — 10 секунд. После принятия сервисом доставки неуспешная отправка повторяется до 10 попыток, с задержками после предыдущей ошибки:

ПопыткаЗадержка
1Сразу
260 секунд
3120 секунд
4300 секунд
5600 секунд
6900 секунд
71800 секунд
83600 секунд
97200 секунд
107200 секунд

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

Вебхук не гарантирует получение каждого результата. При отсутствии события запросите заказ, VPS, аренду или IP. История доставки находится в дашборде; отдельного публичного маршрута истории нет. Поддержка события вроде vm.ip.replaced не означает наличие соответствующего публичного маршрута замены: используйте опубликованный каталог маршрутов.

При отдельной покупке IPv4 событие order.completed содержит ip_id и paid_until, vm_id=null. События order.completed и ip.allocated могут приходить в любом порядке.

События почты​

Почта использует те же URL вебхука, подпись и правила подтверждения. data.event_id для почтового события — строка UUID: исключайте повторы по интеграции, источнику события и ID. created_at передаётся в UTC, api_user_id обозначает клиента. Поля конкретного события присутствуют, когда оно их передаёт; не требуйте все поля во всех событиях.

СобытиеЗначение и поля в data
mailbox.createdЯщик готов: mailbox_id, account_id, ready_at, paid_until; operation_id, если есть связь с операцией.
mailbox.expiringСкоро закончится оплата: mailbox_id, account_id, paid_until, delete_after, hours_before. Пороги напоминаний: 336, 168, 72, 48, 24 и 1 час; используйте полученное значение.
mailbox.renewedИзменён срок оплаты: mailbox_id, account_id, paid_until.
mailbox.suspendedДоступ приостановлен: mailbox_id, account_id, paid_until, delete_after, reason.
mailbox.resumedДоступ восстановлен: mailbox_id, account_id, paid_until, delete_after, reason.
mailbox.deleting_soonЧас до удаления: mailbox_id, account_id, paid_until, delete_after, hours_before=1, reason=payment_expired.
mailbox.deletedЯщик удалён: mailbox_id, account_id, paid_until, delete_after, reason; operation_id при явной операции удаления.
mailbox.account_changedИзменён владелец: mailbox_id, account_id нового владельца, previous_account_id; api_user_id относится к новому владельцу.
mail.message.receivedВходящее письмо: mailbox_id, account_id, folder, uid, uidvalidity, message_id. Без тела письма и содержимого вложений.
mail.operation.succeededОперация успешна: operation_id, kind, account_id, mailbox_id, error=null.
mail.operation.failedОшибка операции: те же идентификаторы и публичный код error.
mail.operation.uncertainРезультат операции не подтверждён: те же идентификаторы и error. Перед следующими действиями проверьте операцию.

order_id добавляется, когда событие удалось связать с заказом Cloud API. События ящика и order.completed, order.failed, order.refunded, order.review могут описывать одно действие. События заказа содержат order_type (mail_purchase, mail_renewal, mail_upgrade, mail_delete), mailbox_id, mail_operation_id, сумму и, когда подтверждён, paid_until. Для сверки оплаты используйте заказ, для текущего состояния — ящик.

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

{
"event": "mailbox.deleting_soon",
"timestamp": "2026-11-19T11:00:00.000Z",
"data": {
"event_id": "bbdd7efe-d7b0-4bf6-b81c-629454143934",
"created_at": "2026-11-19T11:00:00+00:00",
"api_user_id": "customer-42",
"account_id": 12,
"mailbox_id": 5,
"paid_until": "2026-11-18T12:00:00Z",
"delete_after": "2026-11-19T12:00:00Z",
"hours_before": 1,
"reason": "payment_expired"
}
}

Ошибки почтовых операций​

События mail.operation.succeeded, mail.operation.failed и mail.operation.uncertain содержат data.error: null при отсутствии ошибки или публичный код. Для этих событий операций data содержит event_id, created_at, api_user_id, account_id, mailbox_id, operation_id, kind.

КодЗначение
mail_daily_limit_exceededДостигнут лимит получателей за последние 24 часа.
mail_minute_limit_exceededДостигнут лимит писем за последние 60 секунд.
mail_too_many_recipientsСлишком много получателей одного письма.
mail_policy_unavailableПроверка лимитов отправки временно недоступна.
mailbox_unavailableОтправка с ящика недоступна.
mail_operation_failedДругая ошибка почтовой операции.

Лимиты общие для SMTP и API. Суточное окно — последние 24 часа, минутное — последние 60 секунд. Проверка выполняется при отправке; неудачная API-отправка автоматически не повторяется. Лимиты и расход ящика.

© 2026 AdaptGroup LLC. All rights reserved.
30 N Gould St Ste R, Sheridan, WY 82801, USA
Back to top