Callback URLs

Attach callback URLs to virtual machines and volumes for notifications when actions are performed.

Callback URLs can be attached to your virtual machines and volumes, providing you with notifications when actions are performed on the resource.

Callback URLs in Hyperstack

Attach a callback URL during VM deployment

To attach a callback URL to your virtual machine in Hyperstack, follow these steps:

1. Navigate to the VM deployment page in Hyperstack by clicking Virtual Machines in the sidebar and then selecting Deploy New Virtual Machine.

2. Configure your VM as desired, and then click on Configure Additional Settings.

3. In the Callback URL section, enter the URL where you want event notifications to be sent.

   

4. Deploy the VM.

Attach a callback URL to an existing VM

To attach a callback URL to an existing virtual machine, follow these steps:

1. In Hyperstack, navigate to the My Virtual Machines page. Select the VM to which you want to attach a callback URL by clicking on its name.

2. On the VM's details page, go to the Callbacks tab and click Add a New Callback URL.

3. Enter the URL where you want event notifications to be sent, then click Update to save your changes.

Callback Events

When a callback URL is configured for a resource, Hyperstack sends notifications to the specified endpoint whenever events occur that affect that resource. These notifications allow external systems to monitor resource lifecycle changes, track operational progress, and trigger automated workflows.

Callback events are sent for both virtual machines and volumes, and may include lifecycle operations such as creation, deletion, attachment, detachment, and configuration updates.

Virtual Machine Callback Events

The table below lists the events that may be sent for virtual machine resources. These events correspond to lifecycle operations and configuration changes affecting a VM. The Status column represents the sequence of states that the virtual machine transitions through as a result of the associated operation.

Event name	Status	Description
InstanceCreationSuccess	CREATING, BUILD, ACTIVE	Sent when a virtual machine is created and progresses through provisioning until it becomes ACTIVE or fails.
InstanceDeleteSuccess	DELETING, DELETED	Sent when a virtual machine deletion is completed successfully.
InstanceStartSuccess	STARTING, ACTIVE	Sent when a virtual machine is started.
InstanceStopSuccess	STOPPING, SHUTOFF	Sent when a virtual machine is stopped.
InstanceRebootSuccess	REBOOTING, ACTIVE	Sent when a virtual machine is hard-rebooted.
AttachFloatingIPToInstanceSuccess	ATTACHING, ATTACHED	Sent when a public IP is attached to a virtual machine.
DetachFloatingIPToInstanceSuccess	DETACHING, DETACHED	Sent when a public IP is detached from a virtual machine.
AttachVolumeToInstanceSuccess	ATTACHING, ATTACHED	Sent when a volume is attached to a virtual machine.
DetachVolumeToInstanceSuccess	DETACHING, DETACHED	Sent when a volume is detached from a virtual machine.
HibernateInstanceSuccess	HIBERNATING, HIBERNATED	Sent when a virtual machine enters hibernation.
RestoreHibernationInstanceSuccess	RESTORING, ACTIVE	Sent when a hibernated virtual machine is restored.
AttachSecurityRuleToInstanceSuccess	NA	Sent when a firewall rule is attached to a virtual machine.
DetachSecurityRuleToInstanceSuccess	NA	Sent when a firewall rule is detached from a virtual machine.
GenerateVNCConsoleSuccess	NA	Sent when a VNC console URL is generated for a virtual machine.

Virtual Machine Failure Events

The following events indicate that an operation affecting a virtual machine failed. In some cases, the failure of one of these events also means that the underlying VM resource has transitioned to an ERROR state.

Event name	Description
InstanceCreationFailed	Sent when a virtual machine creation operation fails.
InstanceDeleteFailed	Sent when a virtual machine deletion operation fails.
AttachFloatingIPToInstanceFailed	Sent when attaching a public IP to a virtual machine fails.
DetachFloatingIPToInstanceFailed	Sent when detaching a public IP from a virtual machine fails.
AttachVolumeToInstanceFailed	Sent when attaching a volume to a virtual machine fails.
DetachVolumeToInstanceFailed	Sent when detaching a volume from a virtual machine fails.
HibernateInstanceFailed	Sent when a virtual machine hibernation operation fails.
RestoreHibernationInstanceFailed	Sent when restoring a hibernated virtual machine fails.
AttachSecurityRuleToInstanceFailed	Sent when attaching a firewall rule to a virtual machine fails.
DetachSecurityRuleToInstanceFailed	Sent when detaching a firewall rule from a virtual machine fails.
GenerateVNCConsoleFailed	Sent when generating a VNC console for a virtual machine fails.

Volume Callback Events

The table below lists the events that may be sent for volumes. These events provide updates about the lifecycle and attachment state of volumes. The Status column indicates the sequence of states that the volume transitions through as a result of the associated operation.

Event name	Status	Description
VolumeCreationSuccess	CREATING, AVAILABLE	Sent when a volume is created and progresses through provisioning until it becomes available or fails.
VolumeDeleteSuccess	DELETING, DELETED	Sent when a volume deletion begins and when the deletion completes or fails.
AttachVolumeToInstanceSuccess	ATTACHING, ATTACHED	Sent when a volume is attached to a virtual machine.
DetachVolumeToInstanceSuccess	DETACHING, DETACHED	Sent when a volume is detached from a virtual machine.

Volume Failure Events

The following events indicate that a volume-related operation failed. These events allow external systems to detect storage-related failures and respond appropriately.

Event name	Description
VolumeCreationFailed	Sent when a volume creation operation fails.
VolumeDeleteFailed	Sent when a volume deletion operation fails.
AttachVolumeToInstanceFailed	Sent when attaching a volume to a virtual machine fails.
DetachVolumeToInstanceFailed	Sent when detaching a volume from a virtual machine fails.

Callback APIs

Virtual Machine Callback APIs

Endpoint Name	URL	Description
Attach callback to virtual machine	POST/core/virtual-machines/{id}/attach-callback	Creates a callback URL for a specified volume.
Update virtual machine callback	PUT/core/virtual-machines/{id}/update-callback	Updates the callback URL for a specified volume.
Delete virtual machine callback	DELETE/core/virtual-machines/{id}/delete-callback	Deletes a callback URL attached to a volume.

Volume Callback APIs

Endpoint Name	URL	Description
Attach callback to volume	POST/core/volumes/{id}/attach-callback	Creates a callback URL for a specified volume.
Update volume callback	PUT/core/volumes/{id}/update-callback	Updates the callback URL for a specified volume.
Delete volume callback	DELETE/core/volumes/{id}/delete-callback	Deletes a callback URL attached to a volume.

The Event Object

When an action occurs to a virtual machine or volume, here's an example of the event object that gets sent to the specified callback URL:

Attributes of the Event object

resource object

An object containing details about the resource associated with the event.

Show child attributes

id string

Unique identifier for the resource, e.g., "id-of-the-resource."

name string

Name of the resource, e.g., "resource-name."

type string

Type or category of the resource.
Possible values: instance and volume.

operation object

An object containing details about the operation performed.

Show child attributes

name string

Name of the operation performed. For example, "createVM".
Possible values: See supported operations for virtual machines, and volumes.

status string

Status of the operation, e.g., "status."

user_payload object

An object containing user-specific data related to the event.

data object

An object containing additional data related to the event.

Example event object

{
  "resource": {
    "id": "id-of-the-resource",
    "name": "resource-name",
    "type": "resource-type"
  },
  "operation": {
    "name": "operation-name"
    "status": "status"
  },
  "user_payload": {
    // ...
  },
  "data": {
    // ...
  }
}

Back to top