Webhooks
Set a webhook URL and secret in the integration's dashboard settings and enable delivery. Cloud API uses one endpoint for all event types. Delivery history is available in the dashboard. The webhook secret is separate from the API key.
Webhooks are sent from a server with IP address 199.89.134.2.
Envelope
Events arrive as HTTP POST with Content-Type: application/json and 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 is the event type; timestamp is the envelope creation time in UTC. data is event-specific. Resource events also contain data.event_id (a UUID string for mail, numeric for hosting resources) and data.created_at from the source event; order events do not contain those two fields. Some event fields are optional and are omitted when absent at the source.
Order events
| Event | Meaning |
|---|---|
order.completed | Action completed; dedicated purchase is reserved, not yet issued |
order.failed | Order failed; inspect error and transaction history |
order.refunded | Order amount returned to the integration balance |
order.review | Uncertain or partial result requiring clarification |
All four use the order fields shown above: order_id, order_type, api_user_id, status, amount_usd, currency, nullable vm_id, rental_id, error_code and error_message. vm_id is returned only for a completed order. ipv4_renewal additionally includes ip_id and paid_until. A completed VPS purchase can include guest_initialization; it is null when no result is available.
Order types: 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. Backup management orders have zero amount. The payload also includes nullable backup_service_id, backup_id and worker_operation_id. A refund returns the original positive order amount; use event/status to distinguish it from a purchase.
VPS events
order.completed for a VPS purchase also contains nullable application: public application metadata and installer_sha256, without installer contents or credentials. vm.created and vm.reinstalled include the same field for that installation; null means no application. Explicit cloud-init on reinstall replaces the previous application.
For application.installation_mode=background, issuance and billing start while the application is still installing. guest_initialization.status=succeeded does not confirm application readiness, and there is no separate completion webhook. See applications.
Common fields: event_id, created_at, vm_id; api_user_id, order_id and operation_id when present. The table lists additional fields. Creation includes ips as objects containing only address. Deletion includes held_ips matching the VPS deletion result. Failure events include public error_code and error_message.
| Event | Meaning | Additional data fields |
|---|---|---|
vm.rescue.enabled | Rescue enabled | status, rescue |
vm.rescue.enable_failed | Rescue enable failed | requires_review, error_code, error_message |
vm.rescue.disabled | Normal OS boot restored | status, rescue |
vm.rescue.disable_failed | Rescue exit failed | requires_review, error_code, error_message |
vm.reinstalled | OS reinstalled | os, hostname, wipe_extra_disks, status, guest_initialization |
vm.reinstall_failed | OS reinstall failed | requires_review, error_code, error_message |
vm.password.changed | Password changed | login, password_changed, status |
vm.password.change_failed | Password change failed | requires_review, error_code, error_message |
vm.created | VPS created | status, hostname, smtp_blocked, paid_until, ips, guest_initialization |
vm.creation_failed | VPS creation failed | status, requires_review, error_code, error_message |
vm.creation_cancelled | Queued creation cancelled before reservation | status="cancelled", requires_review=false; vm_id=null |
vm.resized | Plan resources changed | status, cpu_cores, cpu_percent, ram_mb, disk_gb, traffic_limit_bytes, resources_applied, traffic_applied |
vm.resize_failed | Plan change failed or partially applied | requires_review, status, cpu_cores, cpu_percent, ram_mb, disk_gb, traffic_limit_bytes, resources_applied, traffic_applied, error_code, error_message |
vm.renewed | VPS renewed | paid_until, resume_pending, auto_start |
vm.traffic.topped_up | Extra traffic added | period_id, quota_revision, additional_bytes, total_additional_bytes, remaining_bytes |
vm.traffic.updated | Traffic quota changed | period_id, quota_revision, previous_limit_bytes, traffic_limit_bytes, remaining_bytes |
vm.ip.attached | IPv4 attached | status, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required |
vm.ip.attach_failed | IPv4 attachment failed | requires_review, error_code, error_message |
vm.ip.replaced | IP replacement reported | status, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required |
vm.ip.replace_failed | IP replacement failed | requires_review, error_code, error_message |
vm.ip.detached | IPv4 detached | status, ip_id, detached_ip_id, keep_ip, addresses, guest_configuration_required |
vm.ip.detach_failed | IPv4 detach failed | requires_review, error_code, error_message |
vm.power.changed | Power command completed | action, status, uptime |
vm.power.failed | Power command failed | action, requires_review, error_code, error_message |
vm.deleted | VPS deleted | status, keep_ips, reason, paid_until, held_ips |
vm.delete_failed | VPS deletion failed | requires_review, error_code, error_message |
vm.expiring | Paid term ending soon | paid_until, hours_before, delete_after |
vm.deleting_soon | One hour before VPS deletion | paid_until, hours_before, delete_after, reason |
vm.suspended | VPS suspended | status, reason, paid_until, delete_after |
vm.resumed | VPS resumed | status, reason, paid_until, auto_started |
vm.traffic.low | Traffic quota nearly exhausted | period_id, quota_revision, starts_at, ends_at, included_bytes, additional_bytes, outgoing_bytes, overage_bytes, remaining_bytes |
vm.traffic.exhausted | Traffic quota exhausted | period_id, quota_revision, starts_at, ends_at, included_bytes, additional_bytes, outgoing_bytes, overage_bytes, remaining_bytes |
vm.shaping.changed | Bandwidth limit changed | previous_reason, reason, limit_mbps, bandwidth_limited_until, manual_limited_until |
Administrative blocks
| Event | Meaning | Additional data fields |
|---|---|---|
vm.blocked | Block active; power-off confirmed | operation_id, status, admin_blocked_at, admin_block_reason |
vm.block_failed | Block execution failed; restriction remains | operation_id, requires_review, error_code, error_message, admin_blocked_at, admin_block_reason |
vm.unblocked | Block removed; VPS remains stopped | operation_id, status, admin_blocked_at: null, admin_block_reason: null |
vm.unblock_failed | Unblocking failed; restriction remains | operation_id, requires_review, error_code, error_message, admin_blocked_at, admin_block_reason |
These events use the same common VPS fields and are sent to the owning integration even when an administrator initiated the action. vm.block_failed does not confirm power-off. Deduplicate by event_id; after a delayed event, read GET /vms/{vm_id} before replacing the displayed state. Do not automatically start the VPS after renewal or unblocking. See administrative blocks.
Initialization and Rescue results
vm.created, vm.reinstalled and completed VPS purchase orders report guest_initialization separately from resource creation:
{
"guest_initialization": {
"status": "failed",
"error_code": "cloud_init_failed"
}
}
Possible statuses: succeeded with error_code=null, failed with cloud_init_failed, or unknown with guest_initialization_timeout after 15 minutes. Custom initialization may fail or remain unconfirmed while the running VPS is retained and its purchase completes. This is not a creation failure or an automatic refund. The resource event omits the field when unavailable.
Successful Rescue events include this nested state:
{
"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"
}
}
}
On exit, rescue.active=false; the VPS can remain stopped if its paid term expired or it was suspended. active means saved Rescue context, not guaranteed SSH availability. access can be ssh, console or null. Failure events carry requires_review, error_code and error_message; read VPS details and the operation for the current state.
Passwords, cloud-init contents, stdout and stderr are not sent in these webhooks. See Cloud-init and Rescue for request rules.
IPv4 events
Common fields: event_id, created_at, ip_id, address, family, vm_id, api_user_id, paid_until when present. A saved address has vm_id=null. Additional fields:
| Event | Meaning | Additional data fields |
|---|---|---|
ip.allocated | IPv4 allocated without a VPS | operation_id, order_id, location_id; vm_id=null |
ip.expiring | Paid IPv4 term ending soon | hours_before, delete_after |
ip.releasing_soon | One hour before IPv4 release | hours_before, delete_after, reason |
ip.suspended | IPv4 suspended | reason, delete_after |
ip.resumed | IPv4 resumed | reason |
ip.released | IPv4 released | reason |
Dedicated rental events
Common fields when present: event_id, created_at, rental_id, plan_id, order_id, api_user_id, status, issued_at, paid_until, overdue_at, finished_at. Credentials are not sent in the webhook: retrieve rental details after dedicated.issued. Additional fields:
| Event | Meaning | Additional data fields |
|---|---|---|
dedicated.preparing | Rental reserved and being prepared | — |
dedicated.issued | Dedicated server issued | — |
dedicated.expiring | Rental payment ending soon | hours_before |
dedicated.overdue | Rental payment expired | release_after |
dedicated.releasing_soon | One hour before rental release | hours_before, release_after, reason |
dedicated.renewed | Rental renewed | — |
dedicated.released | Rental released or cancelled; inspect reason | reason |
dedicated.completed | Rental cleanup completed | — |
dedicated.power_changed | Power command completed | power_state, changed, optional power_action |
dedicated.power_failed | Power command failed | error_code, error_message, requires_review |
dedicated.reinstalled | OS reinstallation completed | os, verified |
dedicated.reinstall_failed | OS reinstallation failed | error_code, error_message, requires_review |
The four power/reinstall events also contain operation_id, action (dedicated_power or dedicated_reinstall) and rental_order_id, the original purchase order. Their order_id refers to a command-specific financial order and is null for these public management routes. status is the rental status; use the event name or operation for the command outcome. verified confirms installation checks, not client application health. Passwords, SSH keys and internal management details are excluded. Read rental details for updated credentials after dedicated.reinstalled.
Backup events
Common fields when available: 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 identifies the original VPS; storage can outlive it. Automatic daily captures may have no order.
| Event | Meaning | Additional data fields |
|---|---|---|
backup_service.created | Storage service activated | — |
backup_service.creation_failed | First capture failed | error_code, error_message |
backup_service.renewed | Storage renewed | paid_until, delete_after |
backup_service.expiring | Warning 24 hours before expiry | paid_until, delete_after |
backup_service.expired | Paid storage expired | paid_until, delete_after |
backup_service.deleting_soon | Warning one hour before deletion | paid_until, delete_after |
backup_service.deleted | Service and its copies deleted | — |
backup_service.deletion_failed | Service deletion failed | error_code, error_message |
backup.created | Copy created | stored_size_bytes, logical_size_bytes |
backup.creation_failed | Capture failed | error_code, error_message |
backup.deleted | Copy deleted | — |
backup.deletion_failed | Copy deletion failed | error_code, error_message |
backup.restored | Original VPS restored | target_vm_id, restore_mode="existing" |
backup.restore_failed | Restore failed | target_vm_id, restore_mode, error_code, error_message |
backup.export_ready | Download archive ready | size_bytes, expires_at |
backup.export_failed | Archive preparation failed | error_code, error_message |
Use order.completed to confirm initial payment or renewal. A pending manual purchase has zero amount until its measured size is known. If the balance cannot cover it, Cloud API deletes the unpaid copy and sends order.failed with backup_insufficient_balance; initial creation success is not forwarded for that failed purchase. Storage and operation statuses describe execution separately from billing.
When auto-renewal is enabled, backup_service.expiring and backup_service.deleting_soon trigger renewal attempts. Warnings are also forwarded when auto-renewal is off or funds are insufficient. The unpaid grace period is 24 hours; inspect the current paid term or renewal result after a warning. Backup warnings do not include hours_before.
Encryption keys, passwords, infrastructure identifiers and signed download URLs are excluded. Failure events use backup_operation_failed with a public message. Obtain download URLs only through the authenticated download route. Creating a new VPS from a copy uses the usual vm.created and vm.creation_failed events.
Field meanings and final warnings
- Dates (
created_at,paid_until,starts_at,ends_at,delete_after,release_after,bandwidth_limited_until,manual_limited_until) are UTC timestamps; optional dates can be null. Byte counters are integers.limit_mbpsis a speed limit in Mbps, or null. - Shaping reasons:
traffic(quota exhausted),bandwidth(sustained load),manual(administrator limit), or null (no limit). The lowest active limit applies separately in each direction.manual_limited_until: nullmeans no expiry when a manual limit is enabled. Public API clients cannot change the administrator's manual limit. statusdescribes the affected resource, not the delivery.reasondescribes the transition, for examplepayment_expired. Do not treat reason strings as the entire event identity.hours_beforeis the warning interval.delete_afteris the VPS/IPv4 deletion or release deadline;release_afteris the dedicated rental deadline.resources_applied/traffic_appliedindicate which parts of a resize were applied.requires_review=truemeans the result needs clarification before another command.period_idandquota_revisionidentify the traffic period and its quota revision.additional_bytesis the added/current quota according to the event;total_additional_bytesis the total after a top-up.remaining_bytesis the remaining quota.guest_configuration_required=truemeans the customer's OS network configuration needs attention.addressescontains resulting addresses;keep_ip/keep_ipsexpresses retention. Read current VPS/IP details for the resulting state.resume_pending,auto_startandauto_starteddescribe restoration after payment. Renewal success does not necessarily mean the VPS is already running.
vm.deleting_soon, ip.releasing_soon and dedicated.releasing_soon warn one hour before removal after the 24-hour unpaid grace period. They are forwarded even when auto-renewal is off or cannot charge the balance. When enabled, Cloud API makes the final renewal attempt. The warning still describes its original deadline; inspect renewal events or the current resource to learn the outcome.
Example final VPS warning:
{
"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"
}
}
Signature verification
X-Webhook-Signature is the lowercase hexadecimal HMAC-SHA256 of the exact raw request bytes, signed with the integration's webhook secret. The secret is not sent. Verify the original bytes before parsing JSON; re-serializing JSON changes the signature input.
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 must be the original Buffer from your HTTP server, before its JSON middleware.
Acknowledgement, repeats and delivery
- Verify the signature and save the event.
- Apply it once: for resource events deduplicate by integration and
data.event_id; for order results use integration,data.order_idandevent. - Return HTTP 200 or 201 after accepting the event. No response body is required. Other codes, including 202 and 204, do not acknowledge delivery.
The HTTP timeout is 10 seconds. Once accepted by the delivery service, an unsuccessful delivery has up to 10 attempts, with delays after the preceding failed attempt:
| Attempt | Delay |
|---|---|
| 1 | Immediately |
| 2 | 60 seconds |
| 3 | 120 seconds |
| 4 | 300 seconds |
| 5 | 600 seconds |
| 6 | 900 seconds |
| 7 | 1800 seconds |
| 8 | 3600 seconds |
| 9 | 7200 seconds |
| 10 | 7200 seconds |
Delivery order is not guaranteed. A late warning must not overwrite a newer paid term in your billing. Recheck current state when events conflict. Order results and resource events can describe the same action; avoid granting the service or crediting a refund twice.
A webhook is not a guarantee that every result reaches your server. If absent, query orders, VPS, rentals or IPs. Delivery history is in the dashboard, not a separate public history endpoint. Some supported events, such as vm.ip.replaced, do not imply there is a matching public replacement route; follow the published route catalog.
For a standalone IPv4 purchase, order.completed includes ip_id and paid_until, with vm_id=null. order.completed and ip.allocated may arrive in either order.
Mail events
Mail uses the same webhook URL, signature and acknowledgement rules. data.event_id is a string UUID for mail events: deduplicate by integration, event source and event ID. created_at is UTC and api_user_id identifies the customer. Event-specific fields are present when supplied by that event; do not require every field in every payload.
| Event | Meaning and fields in data |
|---|---|
mailbox.created | Mailbox ready: mailbox_id, account_id, ready_at, paid_until; operation_id when linked to an operation. |
mailbox.expiring | Payment expires soon: mailbox_id, account_id, paid_until, delete_after, hours_before. Reminder thresholds: 336, 168, 72, 48, 24 and 1 hour; use the value actually received. |
mailbox.renewed | Paid term changed: mailbox_id, account_id, paid_until. |
mailbox.suspended | Access suspended: mailbox_id, account_id, paid_until, delete_after, reason. |
mailbox.resumed | Access restored: mailbox_id, account_id, paid_until, delete_after, reason. |
mailbox.deleting_soon | One hour before deletion: mailbox_id, account_id, paid_until, delete_after, hours_before=1, reason=payment_expired. |
mailbox.deleted | Mailbox deleted: mailbox_id, account_id, paid_until, delete_after, reason; operation_id for an explicit deletion operation. |
mailbox.account_changed | Owner changed: mailbox_id, account_id (new owner), previous_account_id; api_user_id belongs to the new owner. |
mail.message.received | Incoming message: mailbox_id, account_id, folder, uid, uidvalidity, message_id. No message body or attachment content. |
mail.operation.succeeded | Operation succeeded: operation_id, kind, account_id, mailbox_id, error=null. |
mail.operation.failed | Operation failed: the same identifiers and a public error code. |
mail.operation.uncertain | Operation outcome unconfirmed: the same identifiers and error. Check the operation before taking further action. |
order_id is added when the event can be linked to a Cloud API order. Mail lifecycle events and order.completed, order.failed, order.refunded, order.review can describe the same action. Order events contain order_type (mail_purchase, mail_renewal, mail_upgrade, mail_delete), mailbox_id, mail_operation_id, the amount and, when confirmed, paid_until. Use the order to reconcile payments and the mailbox to read its current state.
When auto-renewal is enabled, the one-hour expiry/deletion reminders trigger a renewal attempt from the integration balance. A reminder still describes its original deadline: read the latest mailbox or order to see whether renewal succeeded. Unpaid mailboxes are suspended at expiry and deleted 24 hours later.
{
"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 errors
Events mail.operation.succeeded, mail.operation.failed and mail.operation.uncertain include data.error: null when there is no error, otherwise a public code. For these operation events, data includes event_id, created_at, api_user_id, account_id, mailbox_id, operation_id, kind.
| Code | Meaning |
|---|---|
mail_daily_limit_exceeded | Recipient limit for the last 24 hours reached. |
mail_minute_limit_exceeded | Message limit for the last 60 seconds reached. |
mail_too_many_recipients | Too many recipients in one message. |
mail_policy_unavailable | Sending limit checking is temporarily unavailable. |
mailbox_unavailable | Sending from the mailbox is unavailable. |
mail_operation_failed | Other mail operation failure. |
SMTP and API share the limits. The daily window covers the last 24 hours; the minute window covers the last 60 seconds. Limits are checked when sending; failed API sending is not retried automatically. Mailbox limits and usage.