Skip to main content

Event Callbacks

When creating a virtual machine or a volume, you have the option to include a callback_url field in the body of the request. This allows you to receive events when actions are performed on the resource. Additionally, callback URLs can be added to virtual machines or volumes after they have been created.

In this article


Event callback operations

Virtual machine callbacks

OperationsEndpoints
Attach a callback URL to an existing virtual machine.POST /core/virtual-machines/{id}/attach-callback
Update the callback URL for a virtual machine.PUT /core/virtual-machines/{id}/update-callback
Delete the callback URL for a volume.DELETE /core/virtual-machines/{id}/delete-callback

Volume callbacks

OperationsEndpoints
Attach a callback URL to an existing volume.POST /core/volumes/{id}/attach-callback
Update the callback URL for a volume.PUT /core/volumes/{id}/update-callback
Delete the callback URL for a volume.DELETE /core/volumes/{id}/delete-callback


Attach a callback URL to an existing virtual machine

POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{id}/attach-callback

This endpoint enables you to attach a callback URL to a virtual machine, allowing you to receive events whenever actions are executed on the resource.

In this example, the callback URL "https://example.com" is attached to the virtual machine with an ID of "2".


Path parameters


id REQUIRED integer

The ID of the virtual machine that a callback URL is being attached to.


Request body parameters


url REQUIRED string

The callback URL to be attached to a virtual machine.


Returns


A successful response returns the status of true, a message confirming the successful status, and the URL successfully attached to the virtual machine. Any other response indicates an error has occurred.


Attributes of the Callback object


status boolean

Indicates the status of attaching a callback URL to a virtual machine. When the value is true, it signifies a successful attachment of the callback URL. A status of false indicates that an error has occurred.


message string

An explanation of the status of the callback URL attachment to a virtual machine.


url string

The callback URL that is being attached to a virtual machine.


Example request
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/2/attach-callback" \
-H "accept: application/json"\
-H "authorization: YOUR API KEY"
-d '{
"url": "https://example.com"
}'
Response
{
"status": true,
"message": "Callback URL successfully attached to your instance. Any action events on your instance will be posted to the provided URL",
"url": "https://example.com"
}

note

The same procedures outlined above can be applied to attach a callback URL to an existing volume. However, the POST /core/volumes/{id}/attach-callback endpoint is used instead.


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": {
// ...
}
}


Events for virtual machines

Below is a list of supported operations related to virtual machines, along with the corresponding statuses returned for each operation:

OperationStatus
createVMCREATING, BUILD, ACTIVE, ERROR
deleteVMDELETING, DELETED, ERROR
createSecurityRulePENDING, SUCCESS, ERROR
deleteSecurityRuleDELETING, DELETED, ERROR
startVMSTARTING, ACTIVE, ERROR
stopVMSTOPPING, SHUTOFF, ERROR
hardRebootVMHARD_REBOOT, ACTIVE, ERROR
attachPublicIPATTACHING, ATTACHED, ERROR
detachPublicIPDETACHING, NO PUBLIC IP, ERROR
getVNCAccessURLSUCCESS, ERROR


Events for volumes

Here are the supported operations related to volumes, along with the corresponding statuses returned for each operation:

Operation nameStatus
createVolumesCREATING, AVAILABLE, ERROR
deleteVolumesPENDING_DELETE, DELETED, ERROR

Events for volume attachments

Because volume attachments impact both virtual machines and volumes, events are dispatched to the callback URLs of both resources. Here's an overview of operations and their respective response statuses related to volumes:

OperationStatus
attachVolumesATTACHING, ATTACHED, ERROR
detachVolumesDETACHING, DETACHED, ERROR

Back to top